To Comment Code Or Not To - That Is The Question. My Comments About This Topic... Why Comments Are Even Less Important

It's Friday! So I express this particular post from a philosophical angle as well as technical. And there will be plenty more of these in the future coming from me. It's an opinion from my personal experience as a developer from assembly to C#, nothing more, not from Microsoft or any other source. As developers we gain experiences that transcend trends and changes from other aspects such as programming languages which will continue to change and evolve for the better, for the most part. These aspects we can potentially carry into any programming environment as is currently understood and has been over the past few decades.

So in my 25 years as a software developer, I had a lot of experience with commenting and not commenting source code.

The good thing about comments is they explain the code, in ways that code cannot. However...

The bad thing about comments is often, we can use variable names, method names, class names, namespaces, filenames, folder names etc., that reflect what the code does instead. This enables us that drilldown experience. Furthermore, if you are putting comments in your code and change the code, you may also have to change the comments if applicable, that's extra work. Worst still, change the code and not the comment when it should, we are now out of sync with the code, now we have a problem for future developers who may take over on the code base that you are working on. If you spend time to think about the organization of the code and the flow upfront or refactor as you go along, fewer comments are actually required. After all as developers we prefer to write code, not comments. As developers we prefer to read code, not comments, if the code is well written.

In today's era, if you marry this notion with work items or change requests, then these are often contextual through a bug or task which can change without having an affect on the code. As I see it, if we can see a ChangeSet in TFS, for example, in which the change and the work item (bug, task, operational issue etc.) that was resolved within context to the code change, the requirement for comments in code is reduced even more so. Annotations in TFS help here, but that's another topic, I'll sometime cover soon.

I see comments as a last resort, only needed if it can't already be expressed by the code or through a change request which accompanies the check-in along with something along the lines of a work item.

In my experience, as I moved on in my career as a developer, I focused more on folks being able to understand my code and less on the comments. I spent more time thinking about meaningful names for variables etc and the design of the code.

Some of the best code I've seen, is where there were very few comments, the code was elegantly written, highly maintainable and self-explanatory to someone else looking at it with minimal comments. The most understandable code I saw over 25 years had very few comments. And even then, that was going back to the 1980's and 1990's without work items and Change Sets. Organize the project structure, files, namespaces, classes, methods and variables upfront, means less comments. No more comments on this topic from me. Apologies for the large comment in this blog.