To Comment Or Not To Comment

In a python forum recently, a post was submitted undermining commenting habits of programmers as a substitute of good code. The response on the post was mostly negative. “Thou salt write comments“  seems to be treated  divine command among at beginners. They also accept that it is often violated and therefore always a great sin committed. 

Scope of this discussion is limited to the comments that programmer writes to explain things either to himself or to other programmers who are going to maintain or enhance the code programmer is writing. There are other type of comments that are used to create api docs and intended to be used by code users. I am excluding analysis of those type of comments from this discussion except for some sporadic mention of theirs during categorizations or comparisons.

For a precise discussion and pros and cons of commenting people should read Robert C. Martin’s book Clean Code, specially chapter 4. Also, Martin fowler ‘s great book on refactoring treats comments like smell in certain scenarios and one should read that book to get better understanding. They are good places for balanced analysis on commenting in code and better and specific examples of good and bad commenting in code are provided there. Here I am only planning to outline scenarios in which commenting creates problems starting from the situations that leads to the need of commenting in code at first place.

As an analogy, let’s consider a class in which professor and students are having same mother tongue but due to some reason professor has to deliver a lecture in a different common language that both professor and students understand. This is a very common scenario in India where in most of the universities professors and students have a regional language like Hindi as their mother tongue, but professor delivers lectures in English. We understand that sometimes a professor tends to explain certain topics or examples in their native language. In programming context let’s consider the native language is   like the language in which we write a comment, language in which professor is delivering lecture is like our programming language in which we write our code and professor’s intermittent explanation in native language is like we are writing comments in our codes to explain certain things. 

Now the question is commenting good or bad in programming context becomes whether professor’s explanations in native language in class of lecture in foreign language good or bad. 

Now rather than trying to answer than subjective question right away lets first take different scenario in which such a need can arise and try to understand them. 

Code writer Perspective:

In the class example from professor’s point of view he’ll switch to explanation in native and more convenient language if he himself finds it different to explain complex subject matter in a foreign language. He’ll fall back to an easier approach of explanations which he finds is always going to work. His own inability to explain well in foreign language is one reason. Other scenario in which professor might fall back to native language is in which thinks that though he is explaining well, and he has good command over the language but the students attending his class might not understand it well. He is being considerate to the class. Now we should also assume that the professor is a hardworking and an honest, so he wants her delivered lectures to be understood by every student. And with that intent whenever he feels a need he switches to alternate way of explanation. Now the professor doesn’t have to be like that. He might just spend an hour in a class without giving a damn about how well he is understood. So noble intent of professor also plays an important role in switching. Apart from that the professor might choose to start his class before delivering a lecture by a general introduction of class. What is the purpose and some other general-purpose comments. All these could very well be in a native language. There is other scenario in which the professor might use native language in context of delivering the lecture and that is to build up the lecture material for himself. Even if he is delivering class in foreign language he might very well keep all his notes in his native language.

The reasons we identified above namely difficulty of expression, consideration of target class’s understanding level and intent to make one understood   that make professor to switch language are also the same that make a programmer to write a comment in code. The conclusion that we can draw from above explanation is, if we see comments written in a code we can make following assumption about the programmer writing code: 

1. Programmer is not able to express himself properly in code. 
2. Programmer’s assumption that people going to maintain code might not be smart enough to understand his code.
3. Programmer is writing code with an intent that others should be able to understand his code properly.
4. Programmer’s explanation of general overview of functionality or any such thing which is related to code choice rather code itself.
5. Comments written by programmer to remind himself about the choices he was making. Ideally this is not intended to be present once code is written and used as a substitute or replacement to the detailed design steps, but it might be occasionally present in final version of the code.

Code reader’s perspective:

Like the programmer who is writing the code there is also the perspective of coder who is responsible for maintaining or enhancing the code. Now what are the scenarios in which he also would prefer comments written in a code. 

Let’s go back to our bilingual class and analyze that from student’s perspective. Students will want professor to explain things in native language if they themselves are not able to grasp content in a foreign language. Their familiarity to the language in which content is delivered is limited to the basic understanding of the grammar and simple sentence construction. They are taking class as an opportunity to not only understand the subject but also as an opportunity to understand the language. They may also want explanations in more convenient language if they want to avoid two-step process of translation and comprehension and are only interested in quick summary and want to spend their own time outside class to understand subject through books etc.

As we saw earlier a programmer reading code wants comments helpful in following scenarios: 

1. He is not comfortable in understanding the code.
2. He just wants a quick summary of code in easy to understand way and then tries to understand code from that perspective.

There could be other external factors that might change class and programming environment little different and commenting or explanation in native language could be influenced by those, but we are ignoring any external factor and only considering code reader and code writer as drivers of comments. 

Putting it all together:

We can see that the need of having comments in code might arise from coder as well as from code reader. But it can be avoided, or it might be unnecessary if following conditions are all true:

1. Code writer is expert in expressing himself very well in programming language. 
2. Code writer knows that people who are going to maintain code are all experts in understanding the programming language and it’s intricacies. 
3. Code writer understands that the programming constructs he is using are good enough for anyone reading his code to understand that. 
4. Code reader understands programming language well.
5. Code reader is interested in understanding whole functionality and not just the summary.
6. Code writer doesn’t have to provide and meta information or other information that can not be expressed in code. Assumption here is that everything that programmer wants to express can be expressed in programming language.

Now we can ask ourselves question like” is it at all possible for all the above conditions to be true to avoid need of commenting?”  As our experience says the answer is mostly No. in most of the cases, if not always, there will mostly be a violation of one or more scenario above and therefore we’ll always feel a need of writing proper comments in our code. Though it could simply point out in a direction that our setup in which need of commenting is there is a fragile and compromising one. If situations were ideal, as warranted from an ideal software development environment then commenting might not be needed. 

Assumption in case #6 is certainly not going to hold. We always have to give some details that can not be expressed in form of code. For example, copyright information etc. in all such cases we need some code.

Traditional commenting Vs Programming language commenting.

Here I am considering the aspects of commenting which is suitable for programming language and for that in general. One obvious thing that we look for while commenting in our code is clarity. We intend to make our intention, logic, assumption, behavior and implementation clearer by commenting our code. Our program 

Now what are the problems in writing comments in the programming languages as they are.

Though we took our analogy of professor delivering lecture to draw an analogy to a programmer writing a programmer but that is not a perfect one. Lecture is a oral tradition whether coding falls under written category. So, let’s take another example where commenting is required in written document. This type of comment can be found In form of a footnote in a book. Usually people put a star mark in written document and explain that stared part in document at bottom of the page.  Usually there is one star per page if there are more people put additional start mark on next parts to be explained.

Some people put number on parts requiring explanation and explanation of all the parts numbered is given at the end of the document or book. 

Advantage of this approach is that it doesn’t affect continuity of reading and any side note is just an addendum to original content and context. 

As of now that is not the type of commenting we follow while writing our code. Our commenting style is mostly in-place. Comments are written just near the code for which the code is written. In next section I’ll describe common approaches we follow in our programs for commenting.

Types of Comments in source code:

We can broadly divided comments found in source in 2 categories. 

A) Code comments:  These types of comments are those that are intended to refer a code either to explain that, clarify that put some emphasis on that or to just make a fun. In most cases these code comments can be replaced by a better piece of code. We can further divide this category in many subcategories

1. Instructive: specifying steps to use a code
2. To-do’s :  These come out of laziness or lack of time. Some should-have or good-to-have features are deferred for a future time.
3. Warnings:  don’t use this code until you know what you are doing
4. Explanations: why a particular choice is made.

B) Non-Code comments:  These types of comments don’t refer a specific piece of code. Rather they refer to either whole source code or to give some bigger picture. Journal codes, legal codes , author ‘s info etc are part of this type of codes. In most of the cases they are written in plain English and can not be substituted by codes.

How is commenting supported in current programming languages: 

The languages I worked with usually support two types of comments. Single line and multiline comments. They don’t support nested comments.one possible exception that I know is MATLAB.  Once you have defined your comment boundary you can write anything in your comment section and it Is ignored during code compilation or interpretation.

As explained earlier all of them provide independent commenting capability not in any ways associated with any specific piece of code. And that I think is one of the great disadvantages of the commenting styles of comments supported by programming languages. They cannot be used as a modifier of a source code. And therefore, it becomes programmer’s responsibility to create and maintain this relationship and this could often be missed when code changes hand between developers.

Java supports document comments. Purpose of these comments is to generate Javadoc from the comments written in this section of code. People put these comments for public section of their code to generate api document for these.  The api documents are English language for users of a library. These could not be very appropriate for the people maintaining the library. 

In our present discussion we’ll only focus on those comments that are meant for other programmers who are responsible for maintaining or enhancing the code. So there will be less discussion on documentation comments.

Issues with commenting in programming languages:

One problem with in place commenting is that it assumes or requires rigid association with the code it is describing. To maintain this code comment integrity, we are required to move or change this both pieces together. However, in most of the programming languages they are independent entities and there is no in build association that can be established between them. This makes codes and comments independently movable and over the period of time they become out of sync. Now a comment written to explain meaning of a variable can very easily lost its significance if another variable is declared by other programmer between comment and that variable.  Though it could be a programming crime to commit such mistakes but in absence and check and control by language authorities it is a potential source of problem. 

Another issue with in-place commenting is that we often write our comment in a language based on our understanding of functionality, but implementation could be buggy. There could be another scenario in which our function is doing one thing, but our comment is describing another and the code version is the intended one. This scenario of comment code mismatch with one being true intention might go against our common understanding that comments should always be source of our truth. 

For example, think about a C function that is written to sort a set of numbers. The comment describes sorting algorithm. After some time, same or another programmer finds that algorithms to sort should be changed. He does so but he does not update the comment that was describing earlier algorithm. Now this is a scenario in which bug is not in our code but in our comment. This scenario could be very frequent if there are programmers in project with different commenting habits working on same functionality. 

Is good code always a substitute of a code comment?

Short answer is yes. 

 Think about it in this way, most programming languages support method or function definition where function name is an arbitrary value. Even a single line that you think is   very clever piece of work, can be replaced by function with descriptive name as an alternate to writing a comment above this. Since you can do this for one line and if you have already done it for n lines you can also do it for n+1 lines hence using principle of induction you can remove comment from any place in your program with a descriptive function definition. 

Can code comments be ignored? 

Now let’s assume that all the comments put in the code are bad. so what? can a smart programmer just not ignore them and let it leave for those who want to draw some usefulness out of that ?  In other words, can the presence of comment is of no consequence since they are not able to trigger any action as the actual codes are?

Well there could be one argument that if comments are not there to provide any functionality then can’t they simply be ignored by people not liking them? Can it be a choice to ignore or read comments?

Well it is possible to ignore but here again we need to analyze that from comment writer’s perspective. Is the comment informative, instructive, cautionary or something else? In some cases, a comment from programmers could be just to warn a user from possible repercussions of use of code. For example, a comment advising against use of functions since it takes ages to run. A programmer who wants to run faster version of method may not like to use it, but he can do so potentially if he has not read the comments. 

As we saw earlier, the method definition can always give it a suitable name suggesting that it is a long running method. But if programmer choose to give a not very descriptive name and just to add a comment in source code or document then user might be a victim of doing something bad just because he didn’t read the comment.

Appropriate comments:

Common assumption is that code will always be read by programmers. But that is true only to a certain extent. This is why I think the best way to communicate between programmers should be through programming language and not through a natural language. There are scenarios in which sometimes you treat fellow programmer as a human and sometimes even our reader of program might not be programmers. One such type of readers could be lawyers in case of plagiarism and other such disputed. Sometimes an auditor or business manager might peek into it. Whenever there is a possibility of part of our program to be read by those who are not programmers we need to put that part in natural language if we want them to avoid trouble of learning programming languages. 

And that I think can be treated as a guideline. Programmer to programmer communication should happen in programming language programmer to other human communication should happen in natural language. Keeping in mind that programmers may turn to humans in some cases and that creates a grey area that we need to identify and address as much as we can.

Conclusion:

1. We can almost always avoid code comments and substitute it with appropriate code.
2.  One type of code comments which may not be avoided or substituted are TODO’s
3. Some of the Non-Code comments that are used as a substitute of other tools should be avoided. 
4. When communication to a human and not to a programmer is intended then comments should be used.