Comments are always wrong - right or wrong?

Question

I stumbled upon this blog about how no one should read comments, and thought to myself all the comments I read that were either incorrectly, dated, or simply confusing. If one simple one never reads comments and / or just uses the regex template to delete ... :-) ... just kidding, but actually, maybe not. At least it looks like comments, and related code should have timestamps. Agree or not?

FYI, the blog seems to belong to this user stackoverflow: Nosredna

Answer 1

An inaccurate comment is as serious as a bad code. If this is a constant problem, I would say that the project has serious problems. Large projects such as PostgreSQL (94M, uncompressed in the src directory) are based on accurate commentary to help programmers quickly figure out. They also take comments very seriously.

edit:

Also, if you cannot summarize what your function does, then who can? After you finish writing a function, writing a comment for it may be a test that you fully understand what is going on. If your mind is still a little dull, it will become very obvious when you try to write a comment. And this is good, which shows that we still need to work.

Answer 2

In the real world, programming doesn't just mean writing code. This means writing code that another programmer can understand and support effectively (or independently, after 3 months).

Any programmer who tells you that comments / documentation is not worth the time it takes to write / support has a number of problems:

• His long-term work (and all the colleagues who must work with his code) will be lower than it can be. People will spend a lot of time understanding code, which can be described in a short sentence.

• The error values ​​associated with his code will be higher than they could be, because all these assumptions and special cases that he forgot to mention will constantly raise people. (How many times have you had to do something “unusual” in your code to get something working, forgot to comment on it to say why you did it, and then thought it looked like a bug and was “fixed”, only to find that you broke things terribly because of a subtlety you didn't remember?)

• If he is too lazy to write down how his code works or should be used, what other shortcuts does he accept? Is he worried about checking for zeros and handling exceptions? Does he make sure his interfaces are consistent? Will it reorganize the method / variable name if its base value changes? Usually poor commenting is just the tip of the iceberg.

• Many such programmers are too focused on “cool things” (for example, optimizing every last cycle from their code or finding a smart way to trick a seemingly simple piece of code into a template for reflection) to understand the commercial (for example, it may have problems with so that his code works and is delivered to deadlines, because it focuses on squeezing out unnecessary performance from it, and not just doing the work)

• How good are his projects? I do most of my design and thinking when I write down documents / comments. Trying to explain things to the reader of my comments, I clear up many flaws and assumptions that I would otherwise have missed. I would go so far as to say that I usually write comments (my intention / design) and then synchronize the code with them. In most cases, if there is an error in my code, this is the wrong code, not a comment.

• He didn’t realize that using good variable names, well-designed named prefixes / conventions and documentation comments, he could significantly better use the fabulous time-saving features of his IDE (autocomplete, intellisense help, etc.) and the code is much faster. with lower defect rates.

Basically, he probably doesn't understand how to write good comments:

1) Comments should act as a brief summary of the code snippet. I can read one short line of text instead of working out the meaning of many lines of code. If you find that you are reading code to navigate it, it is poorly commented. I read the comments to navigate and understand the code, and I only read the code itself when I really need to work with this particular bit.

2) The comments of the method / class should describe to the caller everything they need to know to use this class, without having to look into the black box of the code implementation. They will be able to quickly understand how to use the class / method, and understand all the side effects and "contract" that the API provides - what can be null and what should be set, and what exceptions will be thrown, etc. If you need to read the code to get this, it is either poorly encapsulated or poorly documented.

3) Use tools like my AtomineerUtils addin or Submain GhostDoc , which means that its documentation comments can be synchronized with the code with minimal effort.

Answer 3

Code comments can sometimes be invaluable. Many times I struggled to determine the intent of the code without success. For code of any complexity, it can be useful if the author documents his intention. Of course, well-written unit tests can also make an intention clear.

Answer 4

Personally, I do not write many comments, but the general types of comments that I write:

• (sketch) proves that my code is correct.
• explanations, why not just do the obvious thing (for example: optimization is required, the API that I call causes terrifying hype, the "obvious thing" led to a subtle error).
• a description of the input boundary case requiring special processing, explaining why a special processing code appears
• a reference to a requirement or specification that provides for the behavior performed by a particular line of code
• description of the top level of the sequence of steps: ("first get the input", "now split the shell", "finally parse"), which are not needed if the names of the functions called for each step are well selected and unambiguous in the context, but I'm not going to write a shell do-nothing for a generic function, just to give it a more specific name for one use
• The documentation will be automatically extracted. This is a large proportion of the comments in terms of volume, but I'm not sure that it "really matters."
• things that may be part of the documented interface, but not because they may need to change in the future, or because they are internal helpers that are not needed by third-party users. Therefore, it is useful for the developer to know, but not for the user. Invariants of the private class are included in this - do you really want to read the entire class every time you want to rely on "this member is not equal to zero", or "the size is not larger than the capacity" or "access to this member must be synchronized"? It is better to check the participant’s description before his appointment to see if you are allowed. If someone does not have the discipline not to violate the clearly commented invariant, well, it is not surprising that all their comments are erroneous ...

Some of these things are handled by complex tests, in the sense that if the tests pass, the code is correct (hah), if you also open the test code, you can see special input cases, and if some fool hides comments, he makes the same mistake. like me and refactoring my code to do the obvious thing, then the tests will fail. This does not mean that comments do not do this better in the context of reading code. In none of these cases is reading a comment a substitute for reading code, they are intended to emphasize what is important, but not obvious.

Of course, in the case of automatic documents, this is quite reasonable and probably more useful for viewing the documentation separately.

When debugging, as opposed to making changes, it is more valuable that the code can explain itself. Comments are less useful, especially those particular invariants, because if you are debugging, then there is a reasonable chance that the person who wrote the code + comments made a mistake, so comments can be erroneous. On the positive side, if you see a comment that does not reflect what the code does, there is a reasonable chance that you found a mistake. If you just see what the code does, maybe for a while before you realize that what the code does is not what it should do.

Sometimes good naming is important to replace comments. However, names can be as deceiving as comments if they are mistaken. And frankly, often names are at least a little misleading or ambiguous. I doubt that the author of this blog post will go to replace all the names with "var1, var2, func1, func2, class1, class2 ..." to make sure that they were not distracted by the original author wrong intentions for the code. And I don’t think it would be true to say that "comments are always wrong," than to say that "variable names are always wrong." They are written by the same person at the same time for the same purpose.

Answer 5

Some comments are helpful and good, others are not.

Yes, comments and code should be timestamped, but you should not put them yourself. Your version control system should manage this for you, and you should have access to this information (for example, using cvs annotate or svn blame ).

Answer 6

Comment on why you are doing something, not what you did syntactically.