Code comments can save a lot of time and stress for the next person working in the codebase (spoiler: it’s probably future you) by reducing the effort to understand a piece of code, or the intent behind it. Context switching is expensive; a well-placed explanatory comment can reduce or prevent the need, and allow a developer to continue on with their initial task uninterrupted.
Consider including a comment when...
Code is written a certain way for a particular reason
// We use forEach and push as opposed to Array.from or the spread operator// because both are supported in IE 11 without polyfills.optionsSet.forEach(option => {this.selectOptions.push(option);
You ran into Something Weird during development
/* This component works exclusively in UTC due to bugs / inconsistencies in how * browsers handle daylight savings time in the past. E.g., Safari creates * midnight 4/10/57 should be as 4am UTC but (correctly) displays it assuming a * -500 offset. */
You’ve made a fix for a particular issue or PR
// See https://github.com/CityOfBoston/digital/issues/360
Solution has been copied from elsewhere
// see https://react-dropzone.netlify.com/#!/Previews// Make sure to revoke the data uris to avoid memory leaksif (this.state.file) {URL.revokeObjectURL(this.state.file.preview);