The Art of Code Commenting

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 😄