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. ; 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 leaks
if (this.state.file) {
URL.revokeObjectURL(this.state.file.preview);
