Does commentary style affect how readers understand code?

Question

This question has been obsessing me for the past 2 months.

A while ago a friend who is a great programmer gave me some example codes, and for the first time I've noticed a unique style of organizing comments. He took some effort to design comments in a way that would make me more comfortable with the code itself. For example:

/////////////////////////////////////////////                                                   //                                             //
//  This code prints a basic "Hello world" //
// message to the console screen. You can  //
// change the text in the brackets.        //
//                                         //
/////////////////////////////////////////////

#include <iostream>

int main() {
  cout << "Hello world";

}

when he could have simply written

/* This code prints a basic "Hello world" message to the console, change text in brackets */

 #include <iostream>

int main() {
  cout << "Hello world";

}

This kind of example only on a bigger scale. I find this a little unproductive in professional situations but in a learning situation, it seems ideal.

The question here is, if comment style affects how the reader understands code. In my personal opinion option #1 is prettier to the eye and easier to follow than #2. Does the way you comment on code affect ones ability to comprehend your code, or is it just wasted time and space?

Answer 1

Yes

The layout of a program from a whitespace and comment perspective will have a great impact on how well a developer can read your code.

Prettier to the eye and more easy to follow are subjective and will not be the same for every programmer.

That being said, some developers prefer to see more code on the screen at once, while others prefer to have more whitespace/comments.

At the end of the day, you will be more comfortable reading code that you are used to reading.

Uncle Bob Martin, author of Clean Code makes the argument that comments are frequently used to excuse bad code and should be avoided whenever possible. Instead your code itself should be readable and organized well enough to allow another developer to easily pick it up and begin working.

Answer 2

I believe that code formatting can make a huge difference in readability, but mostly well-formatted (or even just consistently-indented) code gives me a warm, fuzzy feeling that the writer actually took a little care, rather than just cut-n-pasting whatever snippets he or she had on hand.

I'm not so sure about comments. Code that I write, I firmly believe the commentary helps. On the other hand, if I want to understand "enterprise" code that I come across at work, I habitually delete all commentary, reformat the code to have consistent indentation, and print it out on paper to read through in detail, marking basic blocks with pencil, etc.

This contradiction (me: good comments; everyone else: misleading comments) makes me think that comments are vastly overrated. Even my own.

Answer 3

Yes, commenting style affects readability (how can it not?), but I would argue that the example you gave is a very poor style. Excessive formatting is just that: excessive.

Writing good comments is a skill to be practiced and refined, just like writing code.

Answer 4

IMHO, first one is suitable for commenting on what a class does or at the beginning of a source file; second one is suitable for describing what the following code block does. for methods, I'd use

//////////////////////////////////////////////////////////////////////
This code prints a basic "Hello world" message to the console screen. You can change the text in the brackets. 

In addition to other great answers, I think consistency in commentary style is another point. If you use different types of commentary styles for same kind of tasks that would hurt readability of your code rather badly.

Answer 5

The example you give is a bit extreme, but yes, comments have a very important function.

The writer of the code has a mental model of what it needs to do. The comments serve to

• communicate to the reader what that mental model is, and
• express the mapping between the mental model and how the code implements it.

That way, if requirements change, it is more likely that the corresponding changes to the code can be made correctly, either by the original author or anyone who comes along later.

It is also good to try to write the code in such a way that it explains itself, but that is seldom 100% successful, so the comments are necessary.

Answer 6

A quick answer to the question is “Yes”. Comments and commentary style clearly affect the readability and understandability of the code. That's the general idea, but the quality of comment descriptions and their design is purely subjective.

Have you ever tried reading someone else’s code and comments? Most programmers write code and comments based on their own style and level of knowledge. Reading their comments and code is like trying to get into their mind and follow their practices.

One way to avoid this issue is to use a basic “principle/style guide” that briefly describe the basic guidelines for code structure, purpose, and comments. This guide must be consistently followed by the people who write the code and all the rest who might read the code and possibly extend it.

Answer 7

Stylistically, I would go with two forms of comment (for C++/Java)

/**
 * Multi-line comment
 */

or

// Single-line comment

an IDE with syntax highlighting is enough to draw your attention to the comment, you do not need to get fancy with the formatting.

Answer 8

Yes, commenting style certainly affects readability. Any comment style that lets me identify comments quickly so I can avoid reading them helps tremendously when what I'm really trying to do is read the code.

Even better is a code commenting style that lets me use the IDE minimize the comments right out of view altogether, so I don't have to expend the energy to read around them.