How to know the right measure of comments?

Question

I went through PHP, C, C++, Javascript and now I’m working with C#. All this time I’ve always heard that it’s important to have well-commented codes, but I never knew the right measure of comments. Or more comment or less comment.

Also, in C# there’s that comment with three bars that basically generates something like this

/// <summary>
/// 
/// </summary>
/// <returns></returns>

And there’s a comment that usually some programmers put at the top of the code with various information like programmer name, date, version, etc.

So what’s the right amount of comments for them to help you understand the code instead of just polluting it?

Answer 1

I finished my master’s this year, and one of my two advisors, a deep connoisseur of Patterns design, UML and OO preached that over-commenting the code could be an indication of something as serious as a bad Smell.

According to him, explaining briefly what the method does (for example, before the method) is OK. However, commenting on many lines of code within of the method, as I said, may indicate that something is wrong, or may indicate even a gambiarra.

For example, a case he cited quite a lot (he didn’t use this specific code, but the idea is what counts):

public void FinalizarPedido(...) {
    //Verifica se o desconto não passa de 20% do valor total do pedido
    if (descontoEmReais > valorDoPedido * 0.2f) {
        //Erro, desconto maior do que o permitido
        <CÓDIGO A>
    }
    <CÓDIGO B>
}

According to him, the fact that you have to comment on the line before the if and the code within the if, means your code isn’t understandable enough for someone else. That is, the above code could be replaced by something similar to the code below in order to remove the need for comments:

private const float PercentualMaximoDeDesconto = 0.2f;

public float DescontoMaximo {
    get { return valorDoPedido * PercentualMaximoDeDesconto; }
}

public bool DescontoEValido {
    get { return (descontoEmReais <= DescontoMaximo); }
}

public void FinalizarPedido(...) {
    if (!DescontoEValido) {
        <CÓDIGO A>
    }
    <CÓDIGO B>
}

Throughout my master’s degree he always stated this:

"Creating code that a machine understands is easy, hard is creating code that someone else understands"

I don’t know if that’s his phrase, or someone else’s, even from another country. As I agree with that phrase, I never went to discover its real origin.

*One detail: all the code my advisor did was in Java. I adapted it to C# to fit the question.

On the other side is the case of a company where I worked. There was used a metric that could be understood as Percentage of comment lines as a comprehensible and well documented code indicator for audit purposes etc.

Some files had more than 50% comment lines. Others, almost 75% comments.

However, that lot of comments actually had a very different effect.

In addition to disrupting the editing and maintenance of the code (which was not at all fluid to be read), the amount of comments was so much, that unconsciously we ended up "filtering" the comments at the time of reading, and no one really read what was written there.

Answer 2

Documentation

Although the posted example officially calls it a documentation comment and has a comment semantics even, that is, the compiler in its normal operation ignores it completely, consider it as documentation and not as comment.

Is documentation important? Sure. Unless you’re building a prototype, a script very simple, or something disposable, documentation is critical.

I believe that the only "controversy" on the subject is whether private members of a class should be documented as well. Some will say yes, others will find that a simple comment is sufficient, and some will say that it does not need to document the detail of implementation, that only the API public shall be documented.

It is likely that you have put the piece of documentation just to illustrate, but to make it clear, what you cannot do is leave it the way it is there. Many people leave only the skeleton of documentation without content.

I find the documentation feature with /// very good. I would like the formatting to be simpler, probably JSON, Markdown or something. But it was developed at the time that Microsoft was loving XML. Still it’s useful.

Tags

You have tags that help a lot to identify what the class does and how to use it. Remember that documentation should help who is going to use the class. That will be you in the future or another programmer. The documentation, in part carries some of the specification. Indeed it is possible even link for extra documents for notes of these specifications.

As tags have some semantics. The compiler himself knows how to interpret these tags and uses these comments in Visual Studio to better inform the programmer in Intellisense, Object Browser, etc.

You can even create tags customized. There is some sophisticated software to generate well formatted outputs. Perhaps the most modern and active currently is the Sandcastle (has other).

Although I can put it anywhere, I think it lacks, for example, a tag <deprecated>. Perhaps because there is an attribute to identify this in the code. But in the tag you could explain and indicate alternative. It would give more semantics than to put in <remarks>.

Also do not suffer from Swiss Army Knife Syndrome. No one is required to use all tags. Depends on what you’re doing, a simple <summary> is sufficient. In general documenting the parameters and return is also necessary. Specify exceptions that the method can generate is important.

External file

It is possible to include documentation from an external file. I do not find this feature particularly useful. The ideal is to have the documentation as close as possible to what she is documenting. If you’re going to put it in another file, then you don’t need to have a link. Maybe to make it easier to access the file, I don’t know.

But it’s also not the end of the world to use a separate file. Documentation is usually pretty stable. That is, except for improvements in content you rarely touch it. If it is documented only the public part of the class has to be so, after all after you have created a class, a method, you cannot go around changing it too much, at the risk of breaking programs that are using them. If the contract does not change, the documentation does not change.

Difference between documentation and comment

Documentation documents the contract, not the implementation, not the code itself. So it’s good not to call it a comment. Documentation says what the class and the method makes in general lines, helps them to be used.

Header

When you look at list of tags that Microsoft created for you to use, do you find author or date of creation? No.

There is a good reason for this. This type of information must be in version control. It will be stored in SVN, in Git, in Mercurial, TFS, etc. Use the right tool to control authorship. Never use method header for this. In time you will realize that it is counterproductive and/or that no one respects it.

It has recommendations that last longer than they should. What I’m going to say goes for many recommendations on coding style. People need to know why of a recommendation. When people learn only the recommendation they don’t know when to stop using.

• In the '60s I had reason to use it, the code was simple, there were no better tools.
• In the '70s it was something very useful yet.
• In the 1980s it was acceptable as a simple way to document.
• In the '90s it was tolerable, not everyone knew how to do it better, there weren’t always better resources available.
• In this century it’s unbelievable that there’s still that. And there is.

Real example of wrong use

I worked at a major vendor if ERP system and this has always been the method of "documenting" the system. I had access to the latest sources and it’s still like this. And worse, it’s still a mess.

Rarely does someone update the header to indicate the changes (although I don’t know if this is good or bad in this case), when updating, it is common not to put as change. I saw several functions that I know were fully developed by me with someone else’s name because she changed a comma in function. All right, that’s always been the culture there. But it already shows that the headline doesn’t really do much. It’s just pointless bureaucracy.

Imagine what it’s worth to know who created a function 20 years after she left the company. Is the creation date so relevant? Or is the complete history? Version? Version of what? Method? Who controls it? Application version? It will change everywhere every time you change the application version?

How to know the real history, which lines have been changed, the precise sequence, without forgetting anything? Only version control software can do that. Don’t waste time with this type of code information. And I’m not just talking about the author, anything that might become irrelevant or not easy to keep right.

The code does not matter "who and when". This information must be in version control.

Exception

There is a case that the header is admissible. Put legal information such as copyright for example. There are cases where this is useful or even mandatory according to the code license. Usually it is more in the file header and not in the class or method.

Commenting on code

This is where there is most disagreement on the right measure.

Bequest

In the early days of programming the "comment all your code" rule was very important. Many do not know that the languages did not have adequate structures to express the code, had no functions, the variables had to be short (2 characters!) and you had to seek performance above all. Comments were fundamental to understand a program. There were and still are languages that neither variables have. In a language Assembly extensive comments remain important, after all we are talking about an almost illegible language.

But this has all changed in high-level languages. Today comments are hardly necessary. Well, C is a language that still needs a little bit, but more for the common style that C programmers usually program than by current language limitation. C is usually used as a Assembly portable.

Exaggerations

There are those who still think that comments should be extensive. I have already resigned from work that required me to do something like this:

//Este método vai inicializar os componentes
InicializaComponentes();

I swear! But those who think about it today recognize that comments in code should be very limited. Code comments are more difficult to maintain. You are commented on the implementation detail, this can change at any time.

Problems

Let’s face it, nobody likes to comment.

Some people think an outdated comment is better than nothing, some people think it’s worse than nothing. I say it varies from case to case. There is no way to know if it will be worse or better. I think the risk is less not commented something.

The most important thing is that the code is expressive. If it was well thought out, and well built, the comment becomes unnecessary. The code, not the comment, should say as do.

What should be included in the comments?

Comments that give reference to where to find more information to understand the decision, the algorithm chosen, or that explains the formula adopted, are always very appropriate. In some cases this reference may be in the documentation, but not always.

• Is this reference detail of implementation? Is this comment.
• Is it part of the contract? Is it useful for the consumer of the class/method? Is it documentation.

Be careful not to abuse this. Many of these references may fit more in version control than in code. Imagine placing a comment for each ticket of bug that you solved. This goes in the message of commit version control.

Already one link for the answer in Sopt where you won the algorithm ready is up to question of ethics :D

For everything there is exception. Specify a ticket to show a bug which should be avoided in future changes is a good one. You are explaining the because of having adopted a path that does not seem to be the best at first glance.

Semantic commentary

Some comments may have semantics. Ex.: //TODO: xxx, //TOFIX: yyy, //HACK: zzz. There are tools that alert you to some of them. This helps you not to forget that something still needs work. The problem is that people ignore them. When those comments last too long they lose the advantage.

Improving the code before commenting

I will not go into detail here what has already been said in other answers, but keep meaningful names for everything, short methods that do just one task, maintaining the same level of abstraction of others.

Summary

There are some tips to define when to comment:

• say because the code is there and not what it does;
• don’t use } //if (cond), if that is necessary, your if is very large (or while, for, etc..);
• avoid leaving code commented out, code that should not be executed anymore (in the final version before the commit, the moment you’re stirring, okay);
• be very succinct;
• if the code needs comment, it may be too complex (unless the domain is complex);
• comments are good to explain code that got "dirty" by need of optimization;
• avoid surprises that the programmer may have, explaining what is to come (something that may be a WTF), alert to and amplify consequences or workarrounds used;
• avoid redundancy, but use when it’s really useful, think before writing;
• explain the intention of the code when it is not obvious and it is not possible to show it in code in a simple way;
• comments should be simple, not embellishment;
• if the comment information is too large, maybe it should be on an external note;

There are people who prefer to have some tags defined to give semantics to the comment (HACK, REF, TOFIX, SECURITY:, etc). And when none tag seems to be appropriate, it is a sign that the comment should not be there.

Don’t forget that any rule can and should be broken to get a better result. Qualitative experience helps decide this. Don’t forget also that some people will disagree with much of these rules.

References

There are serious studies on the subject. The hard part is finding :)

Some books that may help or disturb you (remember the job I quit? My boss was a fan of these books):

• Code Complete - Steve Mcconnell
• The Pragmatic Programmer - Andy Hunt and Dave Thomas
• Clean Code: A Handbook of Agile Software Craftsmanship - Robert "Uncle Bob" Martin

For example, one of these books, which is almost unanimous among programmers, is opinionated, confused, inaccurate, and especially contradictory, i.e., seems horoscope. He says something great for language and bad for others. But he doesn’t say when to use it. Then people generalize. It doesn’t explain why he uses multiple recommendations. Even when he explains, the inexperienced programmer doesn’t understand when his argument is bad. I’m also not saying that the book is useless.

Answer 3

A serious problem I’ve had with too many comments is that not all programmers who participate in a project are so methodical as to change comments when the code changes, and this problem is aggravated as the amount of comments increases.

With a reduced amount of comments, it is possible to maintain code coherence, but it is necessary that the code is self-explanatory (see @carlosrafaelgn’s reply), so that it can be understood, not only by other programmers, but even by yourself. I have forgotten what a code I made, and to understand it is necessary that the code be clear. Only when this is not possible, should comments be placed in the code.

If the amount of comments is justifiable, it is easier to convince everyone on the team to maintain the comments that exist, because it will be less work.

In C#, there’s still a kind of comment that I strongly recommend, which is documentation. These comments are extremely useful because they provide the means for the tools to document the code in a descriptive way so that it is used as a library, that is, as a black box, without having to know the source code of the method being called.

/// <summary>
/// Classe que representa uma lista de pessoas, e contém métodos para manipular
/// todas as pessoas e obter resultados sobre todas as pessoas como um conjunto.
/// Essa classe pode ser usada no contexto Xpto quando é necessário
/// passar registros de pessoas de um local X para outro Y, pois permite fazer serialização.
/// </summary>
public class ListaDePessoas : List<Pessoa> { ... }

The usefulness of these documentation comments is in describing what the element being documented does. It is of no use to put such a comment, saying exactly the same as the name of the documented entity already says.

/// <summary>
/// Classe que representa uma lista de pessoas.
/// </summary>
public class ListaDePessoas : List<Pessoa> { ... }

The above comment is useless.