4

Documentation — How, What, and When Should I Comment?

 1 year ago
source link: https://devm.io/javascript/javascript-documentation-comment
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.
neoserver,ios ssh client

Hitchhiking through the JavaScript jungle

Documentation — How, What, and When Should I Comment?

Documentation usually ranks behind testing in the most loved topics in software development. And after that, there’s usually only topics like endlessly managing legacy code bases that you haven’t even developed yourself. I admit, I don't really like writing comments in code. I don't really think much of it. However, there are some places in your code where documentation in the form of comments is absolutely necessary. So, let’s have a look at why I find a lot of comments to be nonsensical, and why it’s good form to be prolific in comments elsewhere.

My code is self-explanatory, I do not need comments

The book “Clean Code” was published in 2008 and much of it is still valid today, even if Uncle Bob, his views, and public appearances are up for discussion. Among other things, “Clean Code” teaches you that you should write self-explanatory code that speaks for itself. What do comments do in the code? In many cases, they explain what the code does. Why not write the code so that it’s obvious what it does?

In any case, this sounds like a good idea. But it's not that simple. What constitutes understandable code is up to the individual. What seems obvious to one person may be completely incomprehensible to another. But the solution isn’t to ask for comments in the code review explaining every single line. Here, it’s much better to sit down together with the code and rewrite it so that it’s understandable for everyone involved. Because of this, I think that pair and mob programming are excellent approaches for producing high quality code. Ultimately, the discussion about comprehensibility in the development process moves forward, to when the code is created and not just after the damage has already been done.

But back to our actual topic: comments. Basically, comments are completely superfluous for the JavaScript engine. Developers write comments either for themselves or others involved in the project. Hopefully, we agree that comments like the ones in Listing 1 have no place in our application’s code.

Listing 1: Comments in code

function doSomething(x, y, z) {
  if (!x) {
    return false; // return false if x is falsy
  }
  // ---- first block ----
  const value = x + 10; // adds 10 to x
  ...
  // ---- second block ----
  ...
}

One problem in this example is that some of the comments are obvious. You should avoid comments like this if possible, since they tend to disrupt the reading flow and merely point out facts in the code. Similarly, comments visually divide functions into multiple blocks. If you see that this approach is becoming common in your project, there’s a simple solution: outsource the individual blocks to functions and give them a meaningful name. Mostly, the separator comment already gives you a good hint about potential function names. Admittedly, this isn’t the case in our example.

Inline comments can make sense in some places in the code, namely if they clarify the developer's intention that led to the corresponding code location. And this is only if it’s not immediately obvious. Technical requirements in algorithms are good candidates for these comments, as they can be easily misinterpreted as errors in the code. Here, it’s always good if the comment (or at least the commit containing the comment) contains a reference to a ticket or other further documentation.

But why do inline comments have such a bad reputation? Basically, they’re unnecessary in cleanly implemented code, as the code speaks for itself. Additionally, the biggest danger of comments is that they become outdated. If the source code...


report

Recommend

About Joyk


Aggregate valuable and interesting links.
Joyk means Joy of geeK