The Art of Code Comments - Sarah Drasner

Code Can Describe How, But It Cannot Explain Why.

There are different camps when it comes to code comments. The "clean code" camp says that code should be self-documenting. This misses nuance, and doesn't account for the fact that "clean code" is subjective. Sarah surveyed the crowd with two code examples, and the crowd was split on which one was cleaner.

The code that I think was clean five years ago is not what I think is clean today, and you level up in different ways.

Code comments help teams be more productive.

The job of a more advanced engineer is to make sure that the team can scale efficiently. The job of a senior engineer is to make sure that everyone else can get going and be as productive as humanly possible, and sometimes comments can help with that.

Good comments

There are good comments and there are bad comments.

Categories of good comments:

• What is the why
• Clarify what's not typically legible by humans
• Comments can be like chapters of a book
• This is ok to refactor
• I stack overflowed the bejeezus out of this

What is the why

A good comment doesn't describe what the code below it is doing. It describes why it's doing it. These comments can live on even when the code around it changes.

Less maintenance is required in order to keep these comments around. So if you found a better way to write this, then you probably wouldn't have to rewrite this comment.

Clarify what's not typically legible by humans

/* targets Chrome ≤ 28, Safari ≤ 7, Opera ≥ 14 */
.selector { [;property: value;]; }

Great to tell people what the heck that's for, especially in preparation for a time when you no longer need it. Maybe they solve that browser issue or maybe you're not supporting that browser anymore.

Comments can be like chapters of a book

// GEOMETRY
geometry.addAttribute("customColor", new THREE.BufferAttribute(colors, 3));
geometry.addAttribute( "displacement" new THREE.BufferAttribute(displacement, 3));

// SHADER MATERIALS
uniforms = {
  amplitude: { value: 0.0 }
}
const shaderMaterial = new THREE.ShaderMaterial({
  uniforms: uniforms,
  vertexShader: document getElementById("vertexshader").textContent,
  fragmentShader: document.getElementById("fragmentshader").textContent
});

Commenting or sections of code allows people to get to the piece that's most relevant to them

Necessarily there's gonna be a time when you get to a larger piece of code that just has to exist. Sometimes commenting different sections or making some separation can help people find their way more quickly.

This is ok to refactor

Sometimes you just write some quick and dirty code, either for a rushed deadline, a/b test, or because it's "temporary". Leaving a comment with that context, indicating it's not the ideal approach, helps future maintainers understand and be more comfortable with refactoring it.

I stack overflowed the bejeezus out of this

/*
Webpack amirite?
this is mostly copied from the answer below:
https://stackoverflow.com/questions/26203725/how-to-allow-for-webpack-dev-server-to-allow-entry-points-from-react-router
*/

You might go to that post later and find out there's a better response

Bad comments

Bad comments exist.

• They just say what it s already doing
• It wasn't well maintained
• Hoarders, but for code
• You could have used a better name
• The comments are an excuse for not writing the code better to begin with

They just say what it's already doing

// if foo equals bar ...
if (foo === bar) {
  doSomething();
} // end if

You're reading the same thing twice in two different formats. It gives you no more information and in fact it makes you process things twice. It's mental overhead rather than helpful.

It wasn't well maintained

Bad documentation can be worse than no documentation. There's nothing more frustrating than coming across a block of code where a comment says something other than what the code beneath it does.

The comment is in your code. It's your job to work on it, even if it means deleting it.

If you write your code to be good quality to begin with, that expresses the why and not the how, then you might find that the maintenance issue actually goes away.

Hoarders, but for code

created() {
  window.addEventListener('scroll', () => {
    this.bottom = this.bottomVisible()
  })
  //this.removeExtraItem()
  this.addItemsFromCart()
}

You changed something, you know you like the new code, but you just can't quite get rid of that old code yet, [so you comment it out]

Future you, or your future teammates, will spend a few minutes trying to figure out what went on here. Do we need this, will we need this? It's time wasting to do this to people. Trust your instincts and your version control system, get rid of it.

You could have used a better name

Where the variable or functions names are one letter and then you comment what the thing is here in the file. This is a waste. I know we all hate typing, but if you're using a variable or a function name repeatedly, I don't want to scan to the top of the whole document where you explained what the name did, when you could just use the name precisely.

If it's hard to name, maybe you're giving the function too much responsibility. Refactoring has helped me name and likewise, trying to name has also helped me make my functions smaller. — Mike Kerr

The comments are an excuse for not writing the code better to begin with

This is the crux of the issue for a lot of people. If you're writing code that's half hazard and you're leaning on your comments to clarify. This means the comments are holding back your programming.

We lie to ourselves in myriad ways. We spend time writing a comment that could be better spent making the code a little cleaner.

Do your best

It's said that 30% of a developer's time is spent writing code and 70% is spent reading code. My suggestion would be to spend a moment after you think you're done with a project and review with commenting and legibility in mind.

Try to envision that you're both the author and the reader when you're looking at that code [...] what information do you need to be as productive as possible, what would a younger you need?