Clean Code: How to comment code - Best practices
It is essential that code comments are kept up to date and relevant to help create a clean code base and help your engineering teammates.
Here are my two cents on code comment best practices.
How to comment code?
Express the intent, why are you doing that?
Keep it brief.
Don't use complicated words / slang
Use plain English
Don't over/under comment
For hacks / complicated / smart code, be explicit.
Get really good at naming classes, methods, variables. This increases code readability and helps comments make sense.
Use version control. Avoid @author etc.
If you see a TODO in an error handling block. Keep an eye on it and consider looking for the ticket/JIRA number or following up with the author. Many catastrophes and production outages result from unfinished exception handling.
Use appropriate syntax for example, multi-line vs single line. /** vs //
Be aware that the code will evolve and
In PRs and code reviews, check that any comments are still relevant. Keeping a close eye around changed code / diffs.
Get feedback in your pull requests / code reviews. What do your team think?
On a personal note, I feel that I do not write enough comments.
Over the last few months and going forward, I made it a point to try and identify and comment sections that are less obvious to others.
Something else? Drop it in the comments :)
Philip
Location: Switzerland , Graubünden.