How to write good code comments: "why", not "how"

Hello, Habr! I present to your attention the translation of the article "Writing good comments: the why, not the how" by Jack Franklin.







Commenting out code in a programming environment is often considered a waste of time or a signal that the code can be improved. Here is a quote from the CONTRIBUTING.md file that I found on GitHub (and there are a lot of such examples):

Comments should be avoided. If your code cannot be understood without comments, rewrite it to explain itself.

I believe that in most cases such advice will be unsuccessful and incorrect. I believe this approach has its roots in the learning experiences of most people who have studied programming. When I studied computer science at university (although this advice can be found in many courses, not necessarily university ones), I very much remember in the first semester one teacher who said:

Each line of code should have a comment explaining what it does. Your work in the course will be judged against this criterion.

So, let's say you are a freshly baked student just starting this course. What are you going to do? Comment on the code, of course!

//      bar
const inputValue = process.ENV.bar

//     2
const newValue = inputValue * 2

//     square
const finalValue = square(newValue)

//         
const square = (x) => x * x

People who say comments are bad are actually thinking about comments like this. And they are absolutely right! Comments like the ones above, answering the question "how?" In programming, are completely useless. All these comments did not add anything to the code that cannot be understood from the code itself.

Answer the question "why?"

The problem with the comments above is that they explain how . Explains the steps we take in the code. Such comments are rarely helpful; the code itself is much better at telling you what to do. After all, lines of code are just instructions that tell the computer how to complete a task.



Usually, there is no need for an abundance of comments, because you can write simple code without features or nuances that would give it an incomprehensible look. But sometimes situations arise when it is impossible to write elementary and intuitive code. Maybe it's a bug that you have to work around. Or you inherited happiness from past developers in the form of a system that prevents you from solving the problem the way you would like. Or, at the end of the day, there is simply no easy way to improve your code.



Once I worked in a processing company. Every day we ran a huge SQL query that selected payments to be paid. The query was well optimized - we needed it to be very fast - and extremely complex at that, with many edge cases to consider. We tried very hard to make it as clear as possible. However, this request could never be fully intuitive and easy to understand. It just contained too much code with a bunch of conditions and logic that could only be understood in the context of our company and how it worked.



I wanted to find an example to show here, so I went into the wilds of the React codebase to find something. You don't need to be a React developer to figure it out. So, here is the code that I would like to highlight:

//  key     .    , 
//  key      (, <div {...props} key="Hi" />
//  <div key="Hi" {...props} /> ).     key,   ,
//      jsxDEV   , 
// <div {...props} key="Hi" />,       ,
//    key   . 
if (maybeKey !== undefined) {
  key = '' + maybeKey
}

( And here is a link to it on GitHub ).



Pay attention to the code itself:

if (maybeKey !== undefined) {
  key = '' + maybeKey
}

It's not that hard to figure out what it does. If maybeKey is unspecified, we assign the stringified maybeKey value to key. Note: This is a little JavaScript trick to '' + maybeKeyconvert the contents of maybeKey to a string.



But here the whole question is about why . The comment for this code is great. He points out the problem, gives two examples, and also explains how to solve this problem in the long term and what we are doing in the short term.



If you want to look at any comments that I left in the code I wrote, here is one of them (TypeScript / Closure Compiler) . This is a good example of the type of comments that I find very valuable.



In the end, any code can be understood. After all, code is nothing more than instructions that tell the computer how to proceed. The code can be confusing, but it cannot lie; if time is enough, any developer can go through the code step by step and understand what it is doing. It is much more difficult sometimes to understand why he does it. So leave your coworkers (or your future self in six months) a little context about why and for what your code does what it does. It will be much better.