Why would a company develop an atmosphere which discourage code comments? [duplicate]

Question

I was taught in university to write comments for our programs. As I write comments, I feel like I have a better organization and understand the programs better.

However, I am in a company where most of the code I encounter doesn't have comments. Why would a programmer not write comments? Are there are any objective reasons? Do you think comments are annoying when you read others' code? I don't write comments either, and I can think of some reasons why not:

1. Because I can already easily understand the program.
2. My boss won't care how my program gets the job done.
3. Nobody is likely to pick up my program after I am gone.

The purpose of comments is usually to include explanations for the program, however, I found that in my company, comments are used to cover obsolete code instead. For example:

/* Obsolete code */
New code

What is your opinion on commenting? Should we do it? Or does it depend on the situation?

Answer 1

Too many comments are much worse than too few. They take time to write, and even more time to maintain. Throughout the life of a project, code will always reflect what the program does, comments will be inaccurate the instant the code changes. Once the intent to the code does not match the comment, you are on a slippery downhill slope. Comments are not tested by compilers for correctness, so incorrect comments cannot be detected and corrected by the programmer unless huge amounts of attention to detail, where it makes little difference, is made.

In my experience new programmers often overcomment code with useless comments that add no value. Extreme cases such as this are common

int x ; // Integer x 
// Copy the string bob into fred making sure not to overflow the buffer. 
strncpy(bob, fred,sizeof(bob));  

(The error is intentional to make a point)

However devs putting in too few comments is just as common......

Answer 2

Comments should be done on code "paragraphs". Unless you have a dense one liner, you very rarely need a comment to explain a single command. Anyone familiar with the langauge in question should be able to understand it just by reading it, or looking it up.

What you are trying to document is the logic flow of the code, not the gritty details. For example:

writer = csv.DictWriter(open(args.out, 'wb'), output[0].keys(), dialect='excel')
writer.writeheader()
for row in output:
    writer.writerow(row)
writer.close()
del writer

All by it self, what does this mean? We have to dig into each line of code and put it together to understand what is going on, but we still don't know why. What if this was longer, for a more complicated idea? Compare it to this:

# Dump found entries into a CSV file for Excel
writer = csv.DictWriter(open(args.out, 'wb'), output[0].keys(), dialect='excel')
writer.writeheader()
for row in output:
    writer.writerow(row)
writer.close()
del writer

Anyone who checks this out afterwards understands both the content and objective of this code, without the need to dig into it and learn what it does.

Answer 3

The problem begins with people who are of the opinion that comments explain what code does. Then it's a very easy leap to "why bother commenting" and then to "we don't comment here."

Instead, comments should explain why the code exists.

/* setting foo to 1 here so that biz doesn't run too many times 
 * changed from 6 on 3-Aug-11 for ticket 1234
 */
foo = 1; 

This is, I think, something that should be (but isn't) explained in school.

Answer 4

I worked once in a company that discouraged too much use of comments. Though this was for Ruby on Rails. Ruby is a very expressive language and the Ruby on Rails framework dictates quite clearly where things belong and what they are good for. So using comments in a controller to explain what a method is good for would have been needless. So this may depend on context and language you use. Much can be already explained by using descriptive names for methods and variables. It may even force you to keep methods small and have a single, clearly defined purpose. If it becomes difficult to find a good name for a method, it's most likely because the thing is doing too much and should be split in smaller parts.

Leaving old code and commenting it out is a bad habit. That's what a version control system is used for. If you want to see the former state of a file, use the functionality of Git or SVN or whatever you use. Otherwise you have to scroll through pages and pages of old stuff that makes not much sense in the actual context anymore.

Answer 5

Comments are useful whenever the purpose of the code is not immediately obvious.

Maybe the code could be made clearer, maybe not.

Maybe it's obvious to you, but wouldn't be to someone else.

It's a judgement call.

^{(I get a bit tired of the anti-comments religionists; who often come dangerously close to throwing out the baby with the bathwater. They may be deliberately overstating their case, having understood the problem, but others will just take it on board and add one more absolute to their ignorance. By all means, fight for clearer code; when you've won THAT battle, start fighting against comments.)}

Answer 6

I'd say it depends on the situation. When the code is not too much esoteric and the variable names are well chosen, so that the code is "self documenting", then comments might not be necessary. But when the intent is not clear just by looking at the code (for example when using some obscure math theorem), then a good comment explains the why.

Remember that even if they don't compile, comments need to be maintained to follow the code. Imagine a comment explaining the wrong thing because the code changed, and the developer not being able to figure it out. So too many comments means more unnecessary work. (Is too much or not enough better? That's another debate)

As for your case, do other developers need to take a look at each other's code sometimes? Did you never hear one of them (or yourself) saying "What does this code do? I don't understand anything!". If it is the case, maybe a well placed comment is needed.

Answer 7

Comments are fine, as long as they are used only when necessary and they explain something that is not obvious. The examples of mattnz make that clear. There is nothing that is not obvious in that part of the code since it is just using already documented features. Thus for example by executing man strncpy you can find out everything about this function. Not putting any comments in such code is much better and less confusing for other programmers.

Document only the complex parts of your code, and if necessary the input/output and arguments of your functions/methods; the latter is useful if you want to export your API using a documentation system. Do not forget that when a part of the code is updated, the comments must also be updated, thus the maintenance time is longer; which means that your comments should really worth the effort.

Answer 8

There are mainly two categories of comments:

• Comments explaining code
  As other have mentioned, code and comments tends to drift apart. You may leave a comment before a block of code, but when time goes by, the code changes, and no one updates the comment to reflect the changes. The comment becomes a lie.
  If you really feel that a block of code needs a comment to explain the intention of the code, what you could do instead, is to extract the block of code into a method and give it a name. The name will then become the explanation. And method names don't drift the same way comments does. No one likes to call a method called 'GetData' that actually saves some data in stead. Either the developer would change the name of the method, or see that the change they are gonna make doesn't belong there at all.
  There are some things that can't be part of a name, though. Like why did you choose this algorithm over the other one, or why what seems like a more obvious solution to a problem is no good in this particular case and so on.
  There are other cases where a name want contain all there is to know about the code. If you have a good set of unit tests, (and you should), the test suite will be part of the explanation of both intention and inner workings of the code. And naming your tests is as important as naming your production code.

• Comments disabling code
  When writing new code, its often 'comforting' to keep the old algorithm around for reference, After a while, the code tends to be cluttered with small or larger code blocks disabled by comments. It makes the code harder to read, and the reader must consider if the code is relevant or not.
  There are no need for this type of comments, since every edit to a file should be kept in a source control system anyway. If you need to check how an algorithm was in an earlier version, you should be able to go there and have a look. Every check in should have either an comment describing the intention of the code commit, or an link to a bug report or some thing like that.

Robert C. Martin has written a book called 'Clean Code'. He devoted a whole chapter on comments in code. The book is a good one, and worth both money and time.

Answer 9

In broad terms, we write software to create or add value.

Comments, though, are not part of the binary/executable part of the software, they are a part of the source code aspect of the software. Thus, they are supposed to add value to the source code.

Comments that do not add value are pointless and wrong.

When comments do not match what the code is doing, then the software is wrong and the value is lost.

Writing comments has a cost. If the comments are to have a net positive value then the cost of writing the comments must be less than the value one reaps from them.

Everything else is just details.

Answer 10

Job security is a valid reason. If no one but you understands the code, you cannot be fired.

Note to those that have not read Sarcasm for Really Smart People: Not correctly commenting code is unprofessional.

Answer 11

In my personal experience, comments are useful in two cases:

1. explain the code to the next programmer (if you leave)
2. explain the code to yourself (when you are dealing with thousands of files and can't remember the logic behind them).

The second point is most important and mostly neglectable by some companies, thinking they need comments only in case 1, and if that case isn't in their plans then comments aren't as well..

Plus, isn't programming about making decisions all the time? How could you remember the motives behind a decision if you don't write it down?

I recommend writing comments (even against the company flow), because your productivity is somehow depending on it.

Answer 12

If the company doesn't require comments in code, most programmers won't comment because of their laziness, and they will find a clever excuse why comments are never necessary.

On the other hand, sometimes the comments are really unnecessary (for example at trivial getters and setters in Java), and if company creates an official comment-writing policy, programmers are at risk that they will be forced to write comments even in such situations. An ambitious manager can also mandate very complicated comment templates.

This results in a situation where some programmers do write comments and silently curse the laziness of their colleagues, but do not risk discussing this topic openly, because things could get worse.

Answer 13

Comments are a slippery subject, and you'll find loads of flamewars on the web about the right amount of comments a developer should write.

Personnally I like to relate the need for comments to the "technicality scale" of the code you want to comment. On one end of the scale you have close-to-the-metal code using lots of primitive types, dealing with the system, or code that underwent obscure tweaks for performance reasons. The extreme opposite on the scale is purely domain-related code (usually in the business/domain layer), which in my opinion has to be as expressive as possible, with class, variable and method names reflecting real-life concepts of your domain.

Low-level technical code may require quite a lot of comments, because its purpose might be concealed behind non-obvious technical manipulations, complex algorithms, or primitive types usage. A basic example is if a method returns an int (which I wouldn't encourage, but sometimes lower-level operations have to do that), without a Javadoc-like comment on the method you have no way of knowing upfront if the returned int is an error code, an ID...

Conversely, the more domain-related you get, the fewer comments you need, because the names of objects you manipulate should be self-explanatory.

One additional thought: don't underestimate the power of unit tests as a replacement for comments for code documentation purposes. A well-written unit test immediately tells you what the responsibility of the method is AND is compile-safe AND executable.

Answer 14

Why would a programmer not writing comment, if there are any objective reasons?

Comments take time to write and can sometimes be put on hold for other higher priority work. Haven't you had cases where it was more important to "git-r-done" than comment what was done way back when?

Do you think comment annoying when you read other's code?

Comments can be useful but how many places will let you spend hours writing comments that aren't adding immediate business value?

My overall view is comments are good in moderation. Too much or too little can be a big problem.

Answer 15

They want your code to make sense in and of itself. In the real world, that is not always possible. But it is better to strive for the former and find a way to cope with the latter.

Answer 16

From my perspective, comments should generally be limited to method level comments (Javadoc or .NET XML type comments) for the generation of documentation later and TODO comments. Beyond that, I think in most cases commenting is superfluous, time-consuming, and slightly annoying. If you really think the person who comes behind you can't figure it out, then refactor it or at least put it in its own method with a method level comment.

Answer 17

The only comments I like are the ones explaining why the current design is bad and how to improve it.

Outside those "this is why this sucks" comments, if you can't understand what it does by looking at the code and reading/running the tests then there is no hope.