8

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?

Improve this question
1
  • Both your examples are good examples of poor comment styles for professional code. Comment boxes should not be used, and block comments should also be avoided. Educators seem to love comment boxes though. Commented Feb 21, 2012 at 16:29

8 Answers 8

Reset to default
5

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.

Improve this answer
6
  • 'Easier to follow' is actually one of the easier things to measure and quantify. You can, for example, present randomized groups of competent programmers with a code sample that contains a bug, and time how long it takes them to find it (you first need to establish a baseline though, presenting both groups with a batch of identical code samples; this is even more important if your groups are small or your randomization method may be sub-optimal). Other tasks may include predicting the input, determining algorithmic complexity, or guessing what the code does (multiple choice style). Commented Feb 21, 2012 at 6:54
  • 1
    "comments are frequently used to excuse bad code and should be avoided whenever possible" sounds like utter rubbish to me. What he should have said is "bad code should be avoided whenever possible". Commented Feb 21, 2012 at 10:49
  • 1
    @Sardathrion He does say to avoid bad code. In fact, his entire book is about how to avoid writing bad code. He also says to avoid the common practice of resorting to comments to mask bad code when you could instead write better code. Commented Feb 21, 2012 at 14:54
  • @EricKing: I have not read the book so cannot comment on what the author actually said. However, Robert Greiner's summary reads like "Comments are used to mask bad code, therefore comments should be avoided". I believe this is utter rubbish whoever says it. Using comments to mask bad code is bad practice. Not commenting your code is bad practice. Good code and good comments are good practice. ;> Robert Greiner: could you clarify what you meant? Commented Feb 21, 2012 at 15:26
  • 1
    @Sardathrion you misquoted me. I used to think the same way as you when I first started programming and the truth is, that comments aren't all they are cracked up to be. I suggest checking out Clean Code if you are interested in learning more about writing great code. It really helped shape the way I think about programming and I think it would help anyone that reads it become a better programmer. Commented Feb 21, 2012 at 15:48
7

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.

Improve this answer
2
  • 1
    This deserves a +1 just for the last paragraph alone :-) Commented Feb 21, 2012 at 5:05
  • I used to wish our last programmer used comments. Then I found the part of his code he left comments in. Now I wish our last programmer didn't use comments. Commented Feb 21, 2012 at 15:33
6

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.

Improve this answer
2

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.

Improve this answer
1

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.

Improve this answer
0

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.

Improve this answer
0

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.

Improve this answer
0

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.

Improve this answer

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.