Lately, I've been reflecting a lot on my process of documenting and teaching my code to others. As a young dev 😅, I'm always looking for ways to improve. One thing I've noticed in my past work is that the code commentary often wasn't optimal. Let me tell you, returning to a project that I haven't touched for almost two years and finding only 10 comments across the entire project is hellish. So, I hope you can learn something from this article and my thoughts.
Also, make sure to keep an eye out for my upcoming article specifically focusing on the art of code commenting in .NET. You won't want to miss it! Be sure to follow me to stay up-to-date with all my latest insights and articles.
Comments in code are akin to leaving notes to your future self and to others who might work on the code. Why did I write this piece of code in a certain way? Why did I not choose an alternate approach? Code, by its nature, tells you "how", comments should ideally tell you "why". This is a philosophy I've come to appreciate over the years.
So based on my reflection and my past experience I think the following practices are making a lot of sense. At least to me 😅
Comment the Why, not the What: I strive to write code that is self-explanatory in terms of what it does. My comments are then dedicated to providing context, explaining my decisions, or highlighting any non-obvious aspect of the code.
Keep Comments Relevant: One of the things I've learned the hard way is that outdated or incorrect comments can be worse than no comments. So, every time I update my code, I make it a point to update relevant comments as well.
Avoid Redundant Comments: As tempting as it might be to comment everything, I avoid commenting on the obvious. I believe that if my code is clean and clear, it should largely speak for itself.
Use XML Documentation Comments: I find XML documentation comments an excellent tool to provide information about my code's classes, methods, properties, etc. Not only do they help generate a separate XML file, but they also provide IntelliSense documentation in the Visual Studio code editor, making life easier for me and my team.
Commented-Out Code: Early on, I used to leave commented-out code in my source files, but soon I realized that it creates unnecessary clutter. I've come to rely on source control for remembering old code instead.
In the end, I would say that code commenting is truly an art form. When done right, it can greatly enhance the understandability of your codebase and improve productivity for both yourself and others. And always remember, your comments are a reflection of your thought process, so strive to make them as clear as possible.
I'm sure there are many more insights to be gathered from the vast community of developers out there. So, I encourage you all to share your thoughts and practices you've used over the years in the comments section. Let's learn from each other!
Enjoy coding 😄
Top comments (5)
I'm a fan of fully, deeply commenting public interfaces while keeping inside code as comment-free as possible.
I have even included the "why" in some method names, and although the first impression my colleagues got was bad, after reading it they where like "he's out of the line, but he is right". Something along the lines of:
MoveThisToHereBecauseObscureBusinessReason()To differenciate comments from commented-out code, I leave a space after // for comments and none for commented-out code.
It also make the comments pop out a bit more!
Source control negates the need for commenting out code.
Hey, this article seems like it may have been generated with the assistance of ChatGPT.
We allow our community members to use AI assistance when writing articles as long as they abide by our guidelines. Could you review the guidelines and edit your post to add a disclaimer?
Guidelines for AI-assisted Articles on DEV
Erin Bensinger for The DEV Team ・ Dec 19 '22
Write my tests
Then pseudocode as comments my process for passing the tests and then write the code.
Finally cleanup any comments that are basicly the same as the code.
The end result is commented code i can come back to easily and can be pair reviewed easily (i hope)