Coding standard for clarity: comment every line of code?

https://softwareengineering.stackexchange.com/questions/336430

01-01-2021
|

Pregunta

I've worked in shops that produce life critical software and I've dealt with commenting rules that were meant to keep the code readable and potentially save lives. In my experience though the requirement becomes a brain dead chore to be ticked off of a checklist and doesn't help me stay focused on writing understandable code. It also distracts my peer reviewer from having a more meaningful conversation with me about how to make the code easier to understand.

I've also graded student code that had no comments and seen why they should be marked down for neglecting them.

I understand that using good names, keeping structures simple, functions short, and modules focused will keep the code understandable enough that comments can be minimized.

I also understand that comments should explain why the code does what it does, not how.

Given all this is it even possible to write good coding standards that capture this idea? Ones that will be relevant in a peer review but won't turn into a mindless checklist activity that produces notes no more helpful than: "You forgot to comment on line 42".

An example of the kind of code this rule might require when treated as a line in a checklist:

/* Display an error message */
function display_error_message( $error_message )
{
    /* Display the error message */
    echo $error_message;

    /* Exit the application */
    exit();
}

/* -------------------------------------------------------------------- */

/* Check if the configuration file does not exist, then display an error */
/* message */
if ( !file_exists( 'C:/xampp/htdocs/essentials/configuration.ini' ) ) {
    /* Display an error message */
    display_error_message( 'Error: Configuration file not found. Application has stopped');
}

If it is possible to express this properly in a standards document, and it might simply not be, I'd like to capture an idea along these lines:

Consider a comment for every line, sequence, statement, section, structure, function, method, class, package, component, ... of code. Next consider renaming and simplifying to eliminate any need for that comment so you can delete it. Check in while comments are rare. Repeat until deadline. Then repeat some more

Solución

Michael Durrant's answer is IMHO not bad, but it is not literally answering the question (as he admitted by himself), so I'll try to give an answer which does:

I also understand that comments should explain why the code does what it does, not how.

Given all this is it even possible to write good coding standards that capture this idea?

Obviously you can write a checklist for your code reviews, containing questions like

"if there is a comment, does it explain why the code does what it does?"
"is each line of the code - in its context - either self-explanatory enough that it does not need a comment, or if not, is it accompanied by a comment which closes that gap? Or (preferably) can the code be changed so it does not need a comment any more?"

If you like, you can call this a "coding standard" (or not, if you think the term coding standard should be reserved for a list of braindead rules, easy to answer if they are fulfilled or not, how the formatting of the code should look like, or where to declare variables). No one hinders you to have the focus of your checklist on semantical questions, instead of going the easy route and put only formal rules into it.

At the end of the day, you should be sure your team needs such a checklist. To apply such questions you need programmers with some experience as reviewers, and you need to find out if it will really improve the readability of the code in a team of experts. But that is something you have to work out together with your team.

Otros consejos

Major anti-pattern leading to poor quality code with less clarity

btw readers, the title was originally "comment every line of code?" and you can imagine the instinctive reaction of many of us, myself included. I later retitled to the longer more accurate title.

At first, reading your question I thought, yuch duplicate stuff in comments , but ok, maybe if you have enough strictures on reviews by multiple people... but then again: people makes mistakes, fail to notice inconsistencies, etc. and over time there will end up being differences. On reflection I think the problem is much larger:

Developers will tend to write worse code. They will use more cryptic names and structures because 'its explained in the comment - see!'.

Consider:

living_room_set = tables + chairs.

Now consider:

set = tbls+chrs # Make the set equal to the table plus the chairs

You not only have both more cryptic names and more to read, you also have to look back-and-forth, look at code, what is a set? look left at code, look right at comments, what are tbls, look left at code, look right at comments, what are chrs, look right at comment. Yuch!

Summary

Develop or enhance a commenting standard if you are forced to in your current position as a developer (As a former COBOL programming I've sure seen big ones!) but spent as much of your time, energy and passion arguing against the commenting anti-pattern using the arguments:

Code and Comments get out of sync with each other when only one is changed
Comments may describe what one person thinks but may be wrong and thus cover up bugs
Code becomes harder to read
Good code becomes harder to write
Tendency to have use more cryptic names
Excessive characters to read in code and comments
Different editors use different styles
Requires higher English language proficiency than just coding
Takes time and resources and subtracts from long-term value *

Plus argue for better code without such comments,- in fact have a standard(!) - all variable names must be full_english_words - there's one! So use that 'standards' energy towards the standards of well written code and tests.

One of the two hard problems is naming things - don't side skip the problem with comments.

Given that one of the other problems is premature optimization and that optimization in general can leads to obscure 'why this way' code, this is one area where explanatory comments for apparently poor code may be beneficial although the above caveats still apply.

* tomorrows code

I don't think a coding standards document is the place to specify what is already common sense. The purpose of a coding standard is to guarantee consistence (and avoid arguments) about issues where reasonable people might disagree and there is no single obvious right answer, e.g. naming conventions, indentation etc.

Such commenting as in your example is objectively useless and might be due to an inexperienced developer, or a developer used to work with a build system which mechanically checks for the the presence of comments (a really bad idea, but it exists). In both cases the solution is education, possibly through code reviews.

If you start adding all kinds of "best practices" to the coding standard, you will just end up repeating which is already stated in multiple books. Just buy "Clean Code", "Code Complete" and "The Pragmatic Programmer" to the developer in question, and keep your coding standard lean.

It is not possible. What you are essentially trying to do is nearly to mechanize good judgment.

When writing critical software such as for life supporting medical systems, huge amounts of checklists and whatnot are virtually inevitable. Not only do even smart people make mistakes, a lot of the software for these devices is written by people that aren't very good at their jobs, so the 'system' has to be able to safeguard against sloppy work, making it safe at the expense of marketability.

Your best option is to leave out the rigorous Coding Standard for commenting and lead the team by example. Show other's what good comments look like by striving to produce good quality code that is appropriately commented. Instead of trying to find the ultimate way of describing how to write comments (which are themselves more often than not a judgement call) show the others what you mean on a daily basis with your own code reviews. As the other members read your code they'll follow suit if they feel it's useful. And if they can't then no Standard would help them write better comments to begin with.

Update

My response in quotes for emphasis:

It is my belief the answer that states the comments should not be addressed in Coding Standards and then lists a set of defensive questions to fight it, is the only correct answer.

The issue here is that a Coding Standard is just that, a Standard. Extremely subjective ideas should not be in a Coding Standard. It can be a in a Best Practices guide, but that guide cannot be used against a developer during Code Review. In my personal opinion, a Coding Standard should be as close to Automated as possible. There is so much time wasted in Code Reviews arguing over naming, spacing, tabs, brackets, comments, etc. etc. when ALL of it can be automated. Even the answer about tables and chairs can be automated. LINT'ers allow for dictionaries, Capitalization Checks per concept (Variable, Function, Method, Class, etc.).

Even JavaDoc checking can be implemented by a Robot LINT'er before a Pull Request is accepted. A lot of Open Source projects do this exact thing. You submit your Pull Request, the code is built with a Travis-CI file, including Static Analysis, and it must pass all the Coding Standards which can be objectively expressed. No human chimes in about 'doing it incorrectly' or not 'providing value' with a comment, or the wrong way to name variables, et el. Those discussions provide no value and are best left to a third-party robot which can take the brunt of our emotional coding.

To actually answer the question we would have to address how to write a Standard which addresses how to answer the following question: Did this comment provide value? A Coding Standard can't possibly dictate the 'value' of a comment. Therefor it becomes necessary for a human to go through that checklist. The mere mentioning of comments in a Coding Standard creates a checklist which the Original Poster is wanting to avoid.

That's why comments are usually not processed by the compiler and stripped out. Their value cannot be determined. Is the comment in question valuable; yes or no?. Answering this question is NP-hard. Only humans stand a chance at properly answering it, and even then it can only be answered at the time it's read, by the person who is reading it; where the value of that comment is affected by the weather, his or her home life, the last meeting they just attended and did not end well, the time of day, amount of coffee they've had. I trust the picture is becoming more clear.

How can it ever possibly be expressed properly in any Standard? A Standard isn't useful unless it can be applied consistently and fairly, where fair is more about objectiveness not emotional.

I contest that a Coding Standard should remain as Objective as possible. The way variables are named IS objective. They can easily be checked against a dictionary for proper spelling, grammatical structure, and casing. Anything beyond that is a "pissing match" that is won by the person with the most power or by "brow beating". Something I, personally, struggle with NOT doing.

When I comment, I always comment talking to my future self in the third person. If I come back to this code in 5 years, what would I need to know? What would be helpful, what would be confusing, and what would be out of date with the code? There's a different between documenting code to generate a searchable public API and commenting code which provides value to an unknown third-party, even if that third-party is yourself.

Here is a good litmus test. If you were the ONLY one on the project. You knew you'd be the only one on the project. What would be in your coding standard? You'd want your code to be clean, self explanatory, and understandable to yourself in the future. Would you have a code review with yourself about why you didn't put a comment on every line? Would you review every single comment you created on the 100 files you checked in? If not, then why force others?

Something I believe is missed in these discussions is that the Future You is also a developer on this project. When asking about value, tomorrow's you is also a person that can derive value from the comment. So team size, in my opinion doesn't matter. Team experience doesn't matter, it changes too often.

No amount of comment code reviewing this stop a pace maker from crashing and killing a patient. Once you talk about a comment which affects code, you're now talking about the code not the comment. If all it takes is a missing comment to kill someone, there is something else that smells in the process.

The solution to this type of rigorous way of coding has already been provided as a methodology to writing software itself. And it has nothing to do with comments. The problem with comments is that they have NO impact on the way the product ultimately works. The best comments in the world cannot keep software from crashing when embedded within a pace maker. Or when measuring the electrical signals with a portable EKG.

We have two types of comments:

Machine Readable Comments

Comment styles such as Javadoc, JSDoc, Doxygen, etc. are all ways of commenting the public interface a set of code provides. That interface may only be used by single other developer (Proprietary code for a two person team), an unknown number of developers (e.g. JMS), or for an entire department. This code can be read by an automated process which then produces a different way of reading those comments, ala HTML, PDF, and such.

This type of comment is easy to create a standard for. It becomes an objective process of ensuring every publically invoke-able method, function, class contains the required comments. Headers, parameters, description et. el. This is to ensure that it's easy for another team to find and use the code.

I'm doing something that looks crazy, but it's really not

These comments are here to help other's see WHY this code was written a certain way. Perhaps there is a numerical error in the processors the code is running on and it always rounds down, yet developers typically deal with code which rounds up. So, we comment to ensure that a developer touching the code understands why the current context is doing something would normally seem unreasonable, but in reality was written that way on purpose.

This type of code is what causes so many problems. It typically goes uncommented and is later found by a new developer and 'fixed.' Thus breaking everything. Even then, the comments are only there to explain the WHY not to actually prevent anything from breaking.

Comments cannot be relied upon

Comments are ultimately useless and cannot be trusted. Comments do not normally change the way programs run. And if they do, then your process is causing more problems then it should. Comments are afterthoughts and can never be anything but. The code is all that matters as that is all that's processed by the computer.

This may sound asinine, but bear with me. Which of these two lines really matters?

// We don't divide by 0 in order to stop crashes.

return 1 / n;

In this example all that matters is that we have no idea what 'n' is, there isn't any check for n being 0 AND even if there was, nothing stops a developer from putting n = 0 AFTER the check for 0. Thus, the comment is useless and nothing automated can ever catch this. No standard can catch this. The comment, while pretty (to some) has no bearing on the outcome of the product.

Test Driven Development

What does have an outcome on the product? Industries in which the code being written can literally save or kill someone has to be rigorously checked. This is done through code reviews, code reviews, testing, testing, code reviews, unit tests, integration tests, trials, staging, months of testing, code reviews, and single person trials, staging, code reviews, testing, and then maybe finally going into production. Comments have nothing to do with any of this.

I would rather code that had NO comments, had a specification, had unit tests which verified the spec, studies of the outcomes of running the code on the production device, then well documented code that had never been tested, nor had anything to compare the code against.

Documentation is nice when you're trying to figure out WHY someone did something a certain way, however, I've found through the years that documentation is typically used to explain why something 'clever' was done, when it really didn't need to be written that way.

Conclusion

If you work at a company which REQUIRES every line be commented I GUARANTEE at least two of the software engineers on the project have already written an auto-document program in Perl, Lisp, or Python which determines the general idea of what the line is doing, then adds a comment above that line. Because this is possible to do, it means the comments are useless. Find the engineers who have written these scripts to automatically document the code and use them as evidence to why the 'Comment on Every Line' is wasting time, providing no value, and potentially hurting.

On an aside, I was helping a close friend with a programming assignment. His teacher had set a requirement that every line had to be documented. So I can see where this thought process would come from. Just ask yourself, what are you trying to do, and is this the right thing? Then ask yourself; Is there any way to 'game' the system with this process? If there is, then is it really adding any value? One cannot automatically write unit tests which tests that code meets a certain specification, and if they possibly could, that wouldn't be a bad thing.

If a device has to work under certain conditions because it'll be inside a human, the only way of ensuring it's not going to kill them is years of testing, peer review, trials, and then NEVER EVER changing the code again. This is why NASA is / was still using such old hardware and software. When it comes to life or death you don't just 'make a little change and check it in.'

Comments have nothing to do with saving lives. Comments are for humans, humans make mistakes, even when writing comments. Don't trust the humans. Ergo, don't trust the comments. Comments are not your solution.

There are two different things you allude to when you talk about comments. They're not the same, and the distinction is important.

Documentation tells you about the outward-facing bits of a piece of code - its interface.

Typically tooling will allow you to read them in a 'standalone' fashion, i.e. you're not looking at the underlying code at the same time.

All the interface should be documented (e.g. each method, excluding private methods), and it should describe inputs, outputs, and any other expectations, limitations, etc., especially things which can't be expressed through constraints, tests, etc. (Exactly how much detail and where it goes depends on the project).

Good documentation allows the potential consumer to decide whether, when, and how to use the code.

Comments in source code have a different purpose. They are there for people looking at the source code. They primarily describe the implementation.

Comments are always read in amongst the underlying code.

Comments should explain surprising decisions or complex algorithms, or of options not taken (and reasoning). They are there so future developers can understand the thought processes of their predecessors, and have at hand information which they otherwise might overlook or spend much time seeking, e.g.

# 'map' outperforms 'for' here by a factor of 10  

// This line works around an obscure bug in IE10, see issue #12053  

-- We are going to recursively find the parents up to and including the root node.
-- We will then calculate the number of steps from leaf node to root node.
-- We first use a WITH clause to get the ID of the root node.

You cannot infer anything from the absence of a comment, and the comment may of course be as wrong as the surrounding code or more so. Judgement must be exercised both on the part of the author and on the part of the reader.

Commenting every line is clearly more work of questionable additional value, which comes with an opportunity cost. If you have a rule that says every line must be commented, you will get that, but at the expense of important parts being commented well.

But it's worse than that: the purpose of a comment is defeated if every line is commented. Comments become noise which make code hard to read: obscuring rather than clarifying. Moreover, indiscriminate commenting makes the truly important comments harder to spot.

Neither comments nor documentation provide any sort of measure or guarantee of the quality of code they describe; they are not a replacement for genuine QA. Their purpose is forward-looking, i.e. in the hope that they will help those who interact with it avoid making mistakes.

In summary, your coding standards can and should require documentation (automated checks help spot undocumented functions/methods, but humans still need to check if the documentation is any good). Comments are a judgement call, and your style guide should acknowledge this. Those who never comment, and those who comment without thinking should expect to be challenged.

You can't codify a commenting standard, because you can't know what the important comment will be in advance.

But you still want to make sure the code is commented correctly, since this is life critical code. The solution is to have a standard for the code review - require that code review comments on understandability.

This won't guarantee that it won't turn into a meaningless check list, but it will at least keep it from making the code harder to read. And has the possibility of making it better.

This requires a culture where a code review isn't itself a meaningless gesture, where getting your code sent back as hard to read is a good thing, and not an insult or annoyance. Just as important, one where saying it was unclear, isn't seen as a failure of the reader.

Unreadable code is, to a certain extent, unavoidable. Because the writer is immersed in the context, and will see something as obvious when it's only obvious if you know x, y, or z.

So, you won't be able to have a rule that says give good feedback, but you can spot check the reviews. Even a non-programmer manager could do so -- because the real question isn't was the code written to be readable, but was the code actually readable, which can only be decided by someone who read it.

Comment every line of code? No.

The purpose of the others rules you talk about is precisely to avoid that.

Comments to a readable code are at best redundant, and at worst will throw a reader off looking for the non-existent purpose of the comment.

If you comment whole code which is self-explanatory, you double the amount of reading with out giving any additional information. I am not sure if such redundancy would pay off. One can imagine a reviewer saying that 42 says "display_error" while the comment says "displays warning". But imagine a change in the code. You have two places to correct now. It becomes clear this style has copy-paste negatives.

I would say that optimally the code should not need any comments, other than documentation.

There are styles which go total opposite, if you have doubts about line it's either:

The code is too complicated and should be refactored into a function with a name with a semantic meaning for the portion of code. Be it a complex if or a portion of an algorithm. (Or a clever LINQ one-liner)
If it cannot be simplified, you don't know enough idioms of language.

(I personally am not a fanatic of strict no-comments rule, but I find it as a good initial mindset to go by.)

Given all this is it even possible to write good coding standards that capture this idea?

As for the process. Our standard gave quite much credit to the reviewer. Assuming they are not malicious this works good.

When he asks "What is variable o?", you rename it. If he asks what does this block do, either refactor or comment. If there was a debate whether something is clear or not, if the reviewer did not get it, then by definition it is not. On very rare occasions there was something like 2nd opinion from few friends.

On average, you should get a code understandable by the average programmer in the team. IMO it keeps off the redundant information, and ensures that the code is understandable by at least one other member of the team, which we found a good optimum.

Also, there were no absolutes. Though we were a small group. It's easy to find consensus in group of 5.

The question:

Given all this is it even possible to write good coding standards that capture this idea? Ones that will be relevant in a peer review but won't turn into a mindless checklist activity that produce notes no more helpful than: "You forgot to comment on line 42".

Comments should not seek to educate the reader on the language. A reader should be assumed to know the language better than the writer, but with much less context than the writer.

A reader of this code, from your example, should know that exit() will exit the application - thus making the comment redundant:

/* Exit the application */
exit();

Redundant comments are a violation of DRY, and changes to the code do not necessarily propagate to the comments, leaving comments that do not reflect what the code is actually doing.

However, comments that explain why you're doing something may be valuable - especially if you can't easily communicate the meaning in the code itself.

Python's PEP 8 (the style guide for Python in the CPython standard library) provides the following guideline for inline comments:

Use inline comments sparingly.

An inline comment is a comment on the same line as a statement. Inline comments should be separated by at least two spaces from the statement. They should start with a # and a single space.

Inline comments are unnecessary and in fact distracting if they state the obvious. Don't do this:
x = x + 1                 # Increment x
But sometimes, this is useful:
x = x + 1                 # Compensate for border

Given such an example, I personally prefer to go a step further and would try to eliminate this comment as well. For example, I might arrive at:

border_compensation = 1
compensated_x = x + border_compensation

Making your code self-documenting is not a new idea.

Back to the actual question:

Given all this is it even possible to write good coding standards that capture this idea?

I believe that the PEP 8 guidance and example demonstrates a good coding standard that captures this idea. So yes, I believe it is possible.

I think when you see this kind of commenting, and I write this way myself occasionally, It's because the author is writing the spec out in the comments and then going through and implementing each comment.

If we are challenged to write a coding standard which produces code which is understandable in terms of its required functionality rather than its actually functionality (so that errors can be spotted) then are we really talking about how the specifications are defined, documented and linked to the final product?

edit ----

Just to clarify. I'm not getting into comments vs tdd vs unit tests which best. Or suggesting a comment per line is a good/bad

I'm just suggesting a reason you might see the style of commenting talked about in the example.

And from that questioning whether a coding standard about commenting would actualy be better written as a specification document requirement of some kind.

ie comments are for explaining the purpose the code, which is also what a spec is

Given all this is it even possible to write good coding standards that capture this idea? Ones that will be relevant in a peer review but won't turn into a mindless checklist activity that produce notes no more helpful than: "You forgot to comment on line 42".

This obviously goes above and beyond documentation - this touches how the code is structured, which algorithms are chosen, etc. It may even touch on requirements analysis and design.

My #1 rule is "Don't document the obvious." The #2 rule is "Write obvious code".

For safety-critical code (which I've never had to work on, thank God), this is a necessary but nowhere near sufficient first step. It may even have to come down to mandating what language features must be avoided (I've seen more than one standard mandating "Thou shalt not use scanf( "%s", input ); for any reason").

The self-documenting code best practice is not a mainstream consensus - while it is widely acceptable that easy-to-understand code is better than cryptic code, not everyone agrees on whether or not complicated code must always be refactored or if it's OK to comment it.

But this debate is about pieces of code that are difficult to understand - and you are talking about commenting each and every line of code. Lines of code that are difficult to understand should be very rare - if most of your lines are complicated like this than you are overusing smart-ass one-liners and you should stop! Sure, a line's role may be a bit hard to understand sometimes, but that's it's role in the context of a bigger piece of code - what the line itself does is almost always straightforward.

So, you should not be commenting lines - you should be commenting pieces of code. Specific comments may be placed near the lines they refer to, but these comments are still referring to the bigger code. They do not describe what/why the line does - they describe what it does in that code and/or why is it needed in that code.

So, it is not lines that should be commented but bigger pieces of code. Should every piece of code be commented? No. Harold Abelson said that "Programs must be written for people to read, and only incidentally for machines to execute". But comments are only for people to read - the machine does not execute them. If your coding standards force writing redundant comments on every line/piece-of-code you are not just burdening the developer who needs to write them - you are also burdening the developers who will have to read them!

This is a problem, because when most of the comments you read are redundant, you stop paying attention to them(because you know they'll just be redundant junk), and then you'll miss out the important comments. So I say - write only the important comment, so that when someone see a comment in the code they'll know it's worth to read it in order to understand the code.

IMHO it should do both. Commenting every line is silly, because you wind up with lines like

  i++;    /* Increment i */

with absolutely no clue as to why you'd want to increment i. Expand on that a bit, and you have the typical Doxygen style of comments, which produce a large amount of verbiage without supplying any idea of what the code is for, or how it works. (At least as far as I have ever seen: I admit that it might be possible to write useful documentation using a system like that, but I'm not holding my breath.)

OTOH, if you write a good comment block at the head of the function (or whatever grouping is logical), describing both what is to be accomplished, and how, if it's less than obvious, you have something that's useful. If you're me, you might even include LaTeX code for relevant equations, or references to papers, e.g. "This implements a WENO scheme for solving Hamilton-Jacobi equations, as discussed in..."

It's time to bring back flow charts! (not really but hang on a minute)

The other day I found my old flowcharting template. I have only used it for homework and jokes (you gotta love a good silly flowchart). But even by this time most commercial programmers that were still using flow charts were generating them automatically from the code (which completely undermines the original purpose of the flowchart, which was to be an aide in writing better code and was quite useful in machine code. However with higher level languages the flowchart changed from being a crutch to a hoble. Why? the abstraction of the flowchart was the same as the code. The comments shown are a hobble in that they are at the same level of abstraction as the code. Good comments are at a different level of abstraction than the code. The easiest way to do this is to use comments for why while the code handles what. Other ways are to breakdown complicated steps to simpler alternates or to have manager level abstracts.

I'll answer the question as stated:

Given all this is it even possible to write good coding standards that capture this idea?

Yes. WYSIWYG. A good coding standard is literally "is is clear to the reader what the following code does and why".

In other words, my code review comments about code readability literally, 1-1, arise out of my mental state of

I, as a reader, (better yet, as a minimal standard, a mental model of a less-experienced but reasonable reader), would not understand the following code's purpose, or method of working

Generally, people are easy to get on board "this needs more readability" when they hear "I, as a senior developer who you hopefully respect as not being dumb, didn't at first read understand this code or why it's there or what it does, so it needs to be explained".

This shifts the discourse from "you didn't follow meaningless standard" to "your code has a specific readability deficiency leading to practical problem".

A second standard that needs to be made explicit is "2am emergency test".

Can your backup, who's not experienced with this code, figure out what the issue is with the code when debugging it during 2am production emergency bridge call, when you're on vacation in Chilean Andes with no cell phone?

This may sound subjective but is actually easy to practically measure: call up a random junior team member who would be expected to be the one debugging at night in production emergency, and ask them to explain how the particular un-commented code works and why it's there.

This answer covered most issues, however there is one important thing.

I'd like to capture an idea along the lines of: consider a comment for every line, sequence, statement, section, structure, function, method, class, package, component, ... of code.

There are tools to generate documentation from code, like for example doxygen. If you use such tools, then it makes sense to comment files, functions, classes, etc. Even if the function's name is self explanatory, I am still doing it for consistency, because people reading the documentation will be be grateful.

Many of the existing answers are well detailed, but I felt it important to answer:

...[comments] that will be relevant in a peer review but won't turn into a mindless checklist activity...

To me the only comments that could be a standard can be answered by asking what comments are noticed when they're missing. In other words: comments used by IDEs or documentation software.

That being said, this is subjective to what tools are used by the developers, and not all comments used by such software are as useful as each other.

Licenciado bajo: CC-BY-SA con atribución

No afiliado a softwareengineering.stackexchange