Style and recommendations of commenting code

Question

I want to hear from you any advice and experience of writing comments in your code. How do you write them in the most easy and informative way? What habits do you have when commenting parts of code? Maybe some exotic recommendations?

I hope this question will collect the most interesting advices and recommendations forcommenting, something useful that everyone can learn from.

OK, I will start.

1. Usually, I don't use /* */ comments even when I need to comment many lines.

   Advantages: code visually looks better than when you mix such syntax with one-line comments. Most of IDEs have an ability to comment selected text and they usually do it with one-line syntax.

   Disadvantages: Hard to edit such code without IDE.

2. Place "dot" in the end of any finished comment.

   For example:

   //Recognize wallpaper style. Here I wanted to add additional details
   int style = int.Parse(styleValue);
   //Apply style to image.
   Apply(style);
   

   Advantages: Place "dot" only in comments that you finished. Sometimes you can write temporal information, so lack of "dot" will tell you that you wanted to return and add some additional text to this comment.

3. Align text in the enumerations, commenting parameters etc.

   For example:

   public enum WallpaperStyle
   {
       Fill = 100,     //WallpaperStyle = "10"; TileWallpaper = "0".
       SizeToFit = 60, //WallpaperStyle = "6";  TileWallpaper = "0".
       Stretch = 20,   //WallpaperStyle = "2";  TileWallpaper = "0".
       Tile = 1,       //WallpaperStyle = "0";  TileWallpaper = "1".
       Center = 0      //WallpaperStyle = "0";  TileWallpaper = "0".
   };
   

   Advantages: Just looks better and visually more easy to find what you need.

   Disadvantages: Spending time to align and harder to edit.

4. Write text in comment that you can't obtain by analyzing code.

   For example, stupid comment:

   //Apply style.
   Apply(style);
   

   Advantages: You will have clear and small code with only useful information in comments.

Answer 1

Some of the statements below are quite personal, though with some justification, and are meant to be this way.

Comment Types

For the brief version... I use comments for:

• trailing comments explaining fields in data structures (apart from those, I don't really use single line comments)
• exceptional or purpose-oriented multi-line comments above blocks
• public user and/or developer documentation generated from source

Read below for the details and (possibly obscure) reasons.

Trailing Comments

Depending on the language, either using single-line comments or multi-line comments. Why does it depend? It's just a standardization issue. When I write C code, I favor old-fashioned ANSI C89 code by default, so I prefer to always have /* comments */.

Therefore I would have this in C most of the time, and sometimes (depends on the style of the codebase) for languages with a C-like syntax:

typedef struct STRUCT_NAME {
    int fieldA;                /* aligned trailing comment */
    int fieldBWithLongerName;  /* aligned trailing comment */
} TYPE_NAME;

Emacs is nice and does that for me with M-;.

If the language supports single-line comments and is not C-based, I will be more enclined to use the single-line comments. Otherwise, I'm afraid I've now taken the habit. Which isn't necessarily bad, as it forces me to be concise.

Multi-Line Comments

I disagree with your precept using single-line comments for this is more visually appealing. I use this:

/*
 * this is a multi-line comment, which needs to be used
 * for explanations, and preferably be OUTSIDE the a
 * function's or class' and provide information to developers
 * that would not belong to a generated API documentation.
 */

Or this (but I don't that often any more, except on a personal codebase or mostly for copyright notices - this is historical for me and comes from my educational background. Unfortunately, most IDEs screw it up when using auto-format):

/*
** this is another multi-line comment, which needs to be used
** for explanations, and preferably be OUTSIDE the a
** function's or class' and provide information to developers
** that would not belong to a generated API documentation.
*/

If need really be, then I would comment inline using what I mentioned earlier for trailing comments, if it makes sense to use it in a trailing position. On a very special return case, for instance, or to document a switch's case statements (rare, I don't use switch often), or when I document branches in an if ... else control flow. If that's not one of these, usually a comment block outside of the scope outlining the steps of the function/method/block makes more sense to me.

I use these very exceptionally, except if coding in a language without support for documentation comments (see below); in which case they become more prevalent. But in the general case, it really is just for documenting things that are meant for other developers and are internal comments that really need to really stand out. For instance, to document a mandatory empty block like a "forced" catch block:

try {
    /* you'd have real code here, not this comment */
} catch (AwaitedException e) {
    /*
     * Nothing to do here. We default to a previously set value.
     */
}

Which is already ugly for me but I would tolerate in some circumstances.

Documentation Comments

Javadoc & al.

I'd usually use them on methods and classes to document versions introducing a feature (or changing it) especially if that's for a public API, and to provide some examples (with clear input and output cases, and special cases). Though in some cases a unit case might be better to document these, unit tests are not necessarily human readable (no matter what DSL-thingy you use).

They bug me a bit to document fields/properties, as I prefer trailing comments for this and not all documentation generation framework support trailing documentation comments. Doxygen does, for instance, but JavaDoc doesn't, which means you need a top comment for all your fields. I can survive that though, as Java lines are relatively long anyways most of the time, so a trailing comment would creep me out equally by extending the line beyond my tolerance threshold. If Javadoc would ever consider improving that, I'd be a lot happier though.

Commented-Out Code

I use single-line for one reason only, in C-like languages (except if compiling for strict C, where I really don't use them): to comment-out stuff while coding. Most IDEs will have toggle for single-line comments (aligned on indent, or on column 0), and that fits that use case for me. Using the toggle for multi-line comments (or selecting in middle of lines, for some IDEs) will make it harder to switch between comment/uncomment easily.

But as I'm against commented-out code in the SCM, that's usually very short lived because I'll delete commented-out chunks before committing. (Read my answer to this question on "edited-by in line comments and SCMs")

Comment Styles

I usually tend to write:

• complete sentences with correct grammar (including punctuation) for documentation comments, as they are supposed to be read later on in an API doc or even as part of a generated manual.
• well-formatted but more lax on punctuation/caps for multi-lines comment blocks
• trailing blocks without punctuation (because of space and usually because the comment is a brief one, that reads more like a parenthesised statement)

A note on Literate Programming

You might want to get interested in Literate Programming, as introduced in this paper by Donald Knuth.

The literate programming paradigm, [...] represents a move away from writing programs in the manner and order imposed by the computer, and instead enables programmers to develop programs in the order demanded by the logic and flow of their thoughts.2 Literate programs are written as an uninterrupted exposition of logic in an ordinary human language, much like the text of an essay[...].

Literate programming tools are used to obtain two representations from a literate source file: one suitable for further compilation or execution by a computer, the "tangled" code, and another for viewing as formatted documentation, which is said to be "woven" from the literate source.

As a side note and example: The underscore.js JavaScript framework, notwithstanding non-compliance with my commenting style, is a pretty good example of a well-document codebase and a well-formed annotated source - though maybe not the best to use as an API reference).

---

These are personal conventions. Yes, I might be weird (and you might be too). It's OK, as long as you follow and comply to your team's code conventions when working with peers, or do not radically attack their preferences and cohabitate nicely. It's part of your style, and you should find the fine line between developing a coding style that defines you as a coder (or as a follower of a school of thought or organization with which you have a connection) and respecting a group's convention for consistency.

Answer 2

When I went to university I was always taught to comment every line of code and every method header. It was drummed in / indoctrinated to such an extent that you did it without question. Having been part of several Agile development teams at different companies I can say that I may write a comment once in a blue moon.

The reason for this is two fold, first of all we should no longer be writing long monolithic methods that do 101 different things, the class, method and variable names should be self documenting. Take the following login method as an example.

public void Login(string username, string password)
{
    // Get the user entity
    var user = userRepository.GetUser(username);


    // Check that the user exists
    if (user == null)
    {
        throw new UserNotFoundException();
    }

    // Check that the users password matched
    if (user.HashedPassword != GetPasswordHash(password))
    {
        throw new InvalidUsernamePasswordException();
    }

    //Check that the users account has not expired
    if (user.Expired)
    {
        throw new UserExpiredException();
    }

    //Mark user as logged in
    ...
}

This can be rewitten to something that is far more readable and perhaps reusable:

public void Login(string username, string password)
{
    var user = GetUserForUsername(username);

    CheckUsersPasswordMatched(user, password);

    CheckUserAccountNotExpired(user);

    MarkUserAsLoggedIn(user);
}

private void User GetUserForUsername(string username)
{
    var user = userRepository.GetUser(username);

    if (user == null)
    {
        throw new UserNotFoundException();
    }
    return user;
}

private void CheckUsersPasswordMatched(User user, string password)
{
    if (user.HashedPassword != GetPasswordHash(password))
    {
        throw new InvalidUsernamePasswordException();
    }
}

private void CheckUserAccountNotExpired(User user)
{
    if (user.Expired)
    {
        throw new UserExpiredException();
    }
}

You can clearly see from the login method what is going on. You may see this as extra work but your methods are small and only have one job. Additionally the method names are descriptive so there is no need to write any method header comments. If you end up with too many methods this is an indication that the related methods should be re-factored into another object such as a UserAuthenticationService, remember an object should only have one job.

Secondly every single piece of code that you write, including comments, has to be maintained, the more comments you have the more there is to maintain. If you rename a class or a variable you will get a compilation error but if you change the way a section of code works or remove it and do not update any related comments then there will be no compilation error and the comments will hang around causing confusion.

If you are writing an API then I do believe that any public facing interfaces, classes, enumerations should have well written header comments for documentation.

Answer 3

Focus less on the format and more on the content. For instance the comments in you example tell me nothing new. They are worse than worthless as they detract from reading code, and comments such as these are at best a vague reference to what the original programmer thought he was doing at the time he wrote it. I can see from the code example that you are applying a style apply(Style), I can read source. I cannot read your mind, - why are you doing it is what the comment should tell me.
e.g. rather than

//Apply style.
Apply(style);

should be

// Unlike the others, this image needs to be drawn in the user-requested style 
apply(style);

Most of us work in teams on existing code, format the way the rest of the team does,the way it's already being done. Consistency of far more important than pretty.

Answer 4

As much as possible, write your code such that comments would be completely extraneous. Only add comments when the code can't be written in such a way that it would make an important concept obvious.

Answer 5

My own preference is to keep it really simple. I eschew all kind of fancy formatting. The main reason for this is that I think source code should be comfortably editable with even the simplest text editor. I also never hard wrap paragraphs of text but instead let the editor do soft wrapping (no adding of newlines).

Answer 6

1. Pick a documentation system such as doxygen and stick with it. Keep checking on the documents produced.
2. Try to picture someone new to the code base coming in and reading your docs, could they get a running start with it? Interns are actually good for that, sit a new one down with your existing doc base and a simple task and see how far they get, if they stumble, much sure anything you told them to get them going again goes in the docs.
3. Make documentation comments a checkpoint in your review processes.

Answer 7

Here's an "anti-pattern" I've found throughout my job's code: The use of comments as a "change log"; that's what the log in your version control system is for. The code is littered with things like:

// 05-24-2011 (John Doe): Changed this method to use Foo class instead of Bar

and usually often includes the old code that's been commented out (again, that's the point of a VCS system so doesn't need to be in the code after new code is written). Also something to avoid is repeated comments like "Why do we need this?" or worse still, "This should probably be renamed" (because there are sophisticated tools for renaming, so in the time it took you to write that comment you could have renamed the thing). Again, I deal with both of those comments on a regular basis, along the lines of:

// (John Doe) 05-24-2011 not sure why we are using this object?
FooBar oFooBar = Quux.GetFooBar(iFooBarID, bSomeBool);
oFooBar.DiscombobulateBaz();

// (John Doe). This method is poorly named, it's used for more
// than just frazzling arvadents
public int FrazzleArvadent(int iArvadentID)

Answer 8

I often see comments like that, and some tools automatically generate it that way:

/**
 * This is an example, how to waste vertical space,
 * and how to use useless asterixes.
 */

Two lines less:

/** This is an example, how to spare vertical space,
    and how to avoid useless asterixes. */

IDEs and Editors, marginally above the notepad-level, are able to detect comments and to print them in a different color. There is no need to decorate the beginning of the line with asterixes.

You even spare some bytes, if you use a tab for indentation.

If you don't use an sophisticated editor, which renders the comment in a grey tone, the great amount of asterixes will work as an emphasize and attract your attention, which is the opposite of the right thing to do: to stay behind.

Answer 9

The most important recommendation is:
Comment the unexpected, not the obvious!

A comment like this is useless:

// Adds a to b and write the result to c
c = a + b;

It just repeats what the code says and you shouldn't write comments for people who don't understand code as if they don't understand code, they won't read any code and if they don't read any code, they won't read your comments either. Keep in mind that you write comments mainly for other people that are able to understand code about as good as you can understand it.

Thus most of the code shouldn't require comments at all because if most of your code is so clumsy that it cannot be understood without comments, something is wrong with the code or your coding style. Comments should be the exception, not the rule, and this means that the style of your comments is nowhere near as important as your code style.

When placing comments in your code to comment the non obivous, I would recommend to keep them simple, short, and straight to the point. Such kind of commends don't even have to be grammatically correct sentences or use punctuation. They are like additional code, just not for the compiler but for human beings.

// Setting owners must happen on main thread
// and this function must not block
if (!info->owner) return errMissingOwner;

How is that a good comment? A programmer just reading the code may wonder "If there is no owner, why not just setting one instead of returning an error?" The comment gives the answer: Because it must happen on main thread and this statement alone implies the function is probably not running on main thread. Okay but then a programmer may wonder "Why not just dispatching to main thread?" and the comment gives the answer: The function must not block and you cannot guarantee that it won't block unless you know for sure what the main thread is currently doing. So the comment answers all the questions the code alone cannot answer and none of these answers are obvious. Thanks to the comment the reader will know why failing with an error is the only meaningful option here and it also helps future programmers that want to touch the code to not make a stupid mistake.

Yet the real important comments are comments for the purpose of documentation. If somebody only knows your interface but not the implementation, then comments are the only additional source of information on how to use your code correctly and what behavior to expect. These comments should be well readable, usually whole sentences, and use correct grammar and punctuation.

/// Sorts an integer array in place. 
/// The sorting algorithm is stable.
/// Sorting takes O(n * log2(n)) time 
/// and at most (n / 4) * sizeof(int) memory.
///
/// @param array The array to be sorted.
/// @param count Number of elements in the array.
///
/// @return @c false if memory allocation failed and
/// the array wasn't touched, @c true otherwise.
///
bool sortIntArray ( int * array, size_t count );

Without that comment, a programmer may guess what the function does and what the parameters mean but it's impossible to know if the sorting is stable, what bounds on time or memory it will have, or for what reason the operation might fail and what the exact consequence of failing will be.

Answer 10

Code readers usually are trying to answer three questions:

1. What does this class or function do? If this is hard to answer, then it does too much. Code that is hard to document is usually just wrong.
2. How do I use it? An example may be good enough.
3. That code is surprising. Why did you do that? Most likely answers: to work around a bug in third-party components, because the obvious technique proved to be too slow

Everything else should be expressed in the code. Like writing prose, this is an art, and takes a lot of practice. The only way to know if your code is understandable is to get someone else to read it. When they don't understand something, don't explain it verbally. Improve the code. Add comments as a last resort.

If I see "double length" I will ask "What is the unit of measurement?" Don't add a comment. Change the variable name. If I see a block of code and I say "what does this do?", don't add a comment. Extract a function with a meaningful name. If you can't extract a function because it would need 17 arguments, then refactor the code.

Answer 11

Somewhat an odd answer but, the best kind of comments are *no comments*.

If your code is clear, clean and honest:

You do NOT need comments.

Comments lie and are hard to maintain. (one of the many links on Google talking about it)

Try to name your method to hint the intention, adhere to the single responsibility principle whenever possible and your code will read through like a breeze without needing any pesky comments.

(See bronumski's answer for some code examples)