Yes, although one may question what is meant by "intent" exactly. Sometimes the developer's intent is not even completely known to themselves.
I'm using the word 'intent' for intention, goal, plan, purpose; with emphasis on
plan, as in overall design.
(The case where the developer doesn't have an overall plan or intent for the code, I call "throwing spaghetti code at the wall and seeing what sticks".)
While the intent is usually thought of as a willingness to implement some specification correctly
No, that's on a different level of complexity, something that belongs in the supporting documentation, in my opinion.
But that does bring up a really important point/question:
What is the proper level of complexity for useful comments?Ataradov wrote in reply #30 that they don't write comments, and that they often rip them out before analysing code. I think that is most likely due to having had to work too much with code with useless and counterproductive comments, because they indeed do more harm than good. My own preference differs, but I don't like fixed rules
requiring comments either. To me, they're annotations about what the developer is trying to achieve; important when used correctly, worse than useless when used incorrectly.
If you implement a command-line
sort-like utility for some specific data you often use, and instead of reading the data into an array you use a self-organizing data structure (tree, heap) to minimize the human-observable latency (rather than minimizing CPU time used, because you cannot start sorting an array before it is completely read), this
overall design is something that belongs to the documentation, and not somewhere in the comments.
That is, the overall purpose and approach of the code belongs to the documentation, and not in the comments. So that puts a "ceiling" on the level of complexity. And the code itself already tells us what it does, and repeating that in comments is definitely not useful, putting an even clearer "floor" on the level of complexity.
In my opinion, we need to assume understanding of (or capability to find out about) algorithms and known named approaches. For example, if you implement code that calculates Newtonian trajectories for particles in 2D or 3D using
velocity Verlet integration, you should only need to name it in a comment; and not try to explain in the comments how velocity Verlet integration works. Whether one describes velocity Verlet integration in the documentation depends on the overall purpose: I would only do that myself for scientific software (in a separate LibreOffice or LaTeX source file plus .pdf output file).
A majority of cases where I've found comments to be useful is when they describe
expectations, especially unusual or not-easily-inferred ones.
Locking (threads, files, databases) is particularly common. Another is typical parameter values/ranges, when an approach is used that is really fast and precise for almost all cases, and only falls back to a "slow" code path for unusual parameters; and this choice is based on profiling. ("Profiling shows X=Y in 99% of calls, so algorithm Z is used here.")
I also count "use [foo algorithm] to do [bar]" as an "expectation" in the above paragraph. It is common for algorithm implementations to miss some corner cases. A typical one is binary searches when the data contains duplicates: most implementations return
one of the matching entries if found, and not necessarily a specific one (like the first one of the repeated values).
So, there are even more reasons to consider that the code is definitely not proper documentation of what should be. But one may argue that it is the best possible documentation of what it *is*, which is kind of obvious, but often what people mean by documentation.
True. It is often this shift, switching from what the code does, to type a concise comment about any surprising/unexpected/un-inferrible choises made related to the purpose/intent/plan for the code, that makes writing good comments so hard.
(It is also why I believe it is easier to learn to write good comments when one learns that particular programming language or its general approach, rather than later on. We humans are creatures of habits, and learning new habits is hard when one has to (even partially) un-learn a previous habit first.)
Also, I recommend commenting when fixing a bug that was not an obvious bug, to document it.
Most definitely. If you find something unexpected or obscure about the code, and fix or verify it, add a comment about it!
I warmly recommend the common format of starting such comments with the ISO date (YYYY-MM-DD or YYYYMMDD) and username, say
// 2023-12-31 nominalanimal: X is correct, because Y.as it makes investigations using source code versioning systems (svn, git, etc) faster.