Thoughts on Code Comments
Last Updated on: September 16, 2022
Commenting on your code is an essential part of keeping your projects maintainable. It will save you and your team time in the long run.
Over-commenting is a problem. Explaining every last detail creates noise and makes your project harder to work on.
Consider the following:
Less is More.
Say just enough to clarify any unusual situations. Most of the time, your code should do the talking.
Make it Readable
Write the comments for somebody else. Avoid abbreviations that only you know. Write clearly and concisely.
Work in Progress (and TODO: )
In most IDE’s a comment starting with “TODO:” will be highlighted and searchable. Take advantage of this when your code is a work in progress, or you are waiting on something else before fixing/improving.
Update Your Comments
When you modify code, update or remove any comments no longer relevant.
Use Links
Link to API documentation, GitHub issues, or anything relevant and useful.
Leave Your Contact Details
Every team works differently, but leaving your initials or email will help others in the future.
Why So Serious?
We aren’t robots, so add a bit of your personality to lighten the mood. It may make that painful refactoring task a little easier for you or someone else.
Get notified of new posts:
Comments should be a part of programming, for me it is important as any other part.
Sometimes you just don’t have the time and if you know for a fact the comments will not be used, I think it is more pragmatic to just forget them.