Standards of Practice: Code Commenting Style Preferences and Recommendations

Too many programmers in the past 10-15 years (though always a struggle with coders, it has recently gotten much worse) increasingly seem to consider code commenting and documentation passe ("just read the code!" they say) and that it is too time consuming without enough benefit to justify the effort (unfortunately they are simply outright wrong). However, for those that understand the value of good and useful code comments, here are some suggested guidelines...

This can apply to any programming language. I've been online and coding since 1979, and I sometimes slip and say "REM the code there" or "see my remarks in the code", to which most younger developers look very puzzled, and I adjust to "comment out the code there" and "see my comments in the code". :)

I'll not go into a long rant (this time) about how critically important code comments are to proper, professional, and maintainable code with this article, you either grok it or you don't. (verbally patting those on the head who don't grok it yet).

Everyone has their own writing style, this includes books, blogs, coding, documentation, and code comments.

Here is my preferred approach, which perhaps others may find beneficial, including the reasons why I take this approach.

• Use phrases like "trying to", "the goal is", "attempting to", etc., not rigid declarations.
• Focus on the intended outcome rather than asserting what the code definitely does.
• Maintain a neutral, professional tone avoiding using "we/our", profanity, etc.
• Using this style shows that you are open to the possibility that there might be better ways to achieve the same goal, and create a space that invites others to help.

This style of commenting allows for a more open interpretation of the code's intentions. This approach can be beneficial in several ways:

• When providing function comments, use phrasing like "trying to" "goal is to try to" etc. Sometimes the code isn't doing what we actually should be doing, so want to phrase comments in terms of what we're trying to achieve, that way when others look at the actual code, and see there might be a different or better way to achieve the same goal.?
• Don't use the we/our style, keep more neutral/professional, less personal. If temporary comments to self, then feel free to use I, my, me, etc. Take pride and ownership in your work, and own your mistakes, don't try to hide your mistakes (git blame will rat you out anyway), and use those as opportunities to get better and help others improve.

This commenting style approach encourages critical thinking:

• By phrasing comments as attempts or goals, it invites other developers to consider whether the implementation effectively achieves those goals.
• It acknowledges potential improvements: Using phrases like "trying to" implies that there might be better ways to accomplish the same task, fostering a culture of continuous improvement.
• It reduces overconfidence: This style avoids asserting that the code definitely accomplishes something, which can be helpful if the implementation has unforeseen issues or edge cases.
• It promotes discussion: Such phrasing can encourage dialogue among team members about the best ways to achieve the stated goals.
• It aligns with the reality of software development: Code often evolves, and this style of commenting reflects the iterative nature of development.

The style of keeping comments more neutral and professional by avoiding "we/our" can help maintain a more objective and professional tone in the codebase. This more thoughtful approach to code comments documentation can help promote? more robust and evolving codebases.

Happy Coding!