12 ms·

I've met a few senior level programmers who frown on detailed commenting (or commenting at all). I cannot wrap my head around this since I consider it best prac

I've met a few senior level programmers who frown on detailed commenting (or commenting at all). I cannot wrap my head around this since I consider it best practice to comment. A reason given to me was that "it takes up too much time to comment and when you make a code change you need to make a change in the comments as well." To that I say, so what! I would like the future me (or the future programmer) to have full knowledge on what's going on in the code.

wreckimnaked 14y ago
There's some debate on this: http://queue.acm.org/detail.cfm?id=1053354 http://queue.acm.org/detail.cfm?id=1053354
creativename 14y ago
I feel like there are some people who go overboard on the formalities of commenting (specific format, etc.), but in general I can't think of one instance where I've thought "man, I wish I (or someone else) hadn't spent time explaining what this does". I even find that when I write comments to explain what a specific method is intended for, it helps me avoid violating the single-responsibility principle. If I clearly spell out what I'm trying to accomplish, it helps keep me focused. To those who say that the code should be elegant enough to be read on its own, there are some cases where the business logic involved is really what needs to be explained. At the same time, what is elegant and concise for you may appear obfuscated and confusing for someone else. You may argue that they should know all the techniques that you know, but that's just the reality of working with others sometimes.
- lawn 14y ago
  > I can't think of one instance where I've thought "man, I wish I (or someone else) hadn't spent time explaining what this does". There are good uses of comments, but there are also bad ones. From Coding Horror [1] an example: '************************************************* ' Name: CopyString ' ' Purpose: This routine copies a string from the source ' string (source) to the target string (target). ' ' Algorithm: It gets the length of "source" and then copies each ' character, one at a time, into "target". It uses ' the loop index as an array index into both "source" ' and "target" and increments the loop/array index ' after each character is copied. ' ' Inputs: input The string to be copied ' ' Outputs: output The string to receive the copy of "input" ' ' Interface Assumptions: None ' ' Modification History: None ' ' Author: Dwight K. Coder ' Date Created: 10/1/04 ' Phone: (555) 222-2255 ' SSN: 111-22-3333 ' Eye Color: Green ' Maiden Name: None ' Blood Type: AB- ' Mother's Maiden Name: None ' Favorite Car: Pontiac Aztek ' Personalized License Plate: "Tek-ie" '************************************************* Now imagine something like this exists for every function and you're reading the source code... Annoying. Others are less extreme of course, but repeating the code in comments is bad and even harmful if you forget to update the comment as well as the code. DRY is a good principle to have. Of course "all comments are bad" is simply wrong, comments are essential to explain decisions or non-obvious snippets or gotchas.
  - creativename 14y ago
    Yeah, that's exactly the kind of formality and over-commenting that I meant by "I feel like there are some people who go overboard on the formalities of commenting (specific format, etc.)". I saw a lot of examples of that at my old employer where they had tried (and failed) to automate some of their documentation years and years ago. It's nice to have a brief description of what a class (or in many cases, a method) is intended for, etc. As others have said, it saves time each successive programmer from having to fully understand all of the source code.
    - lawn 14y ago
      Ah I see, misunderstood a bit.
  - arethuza 14y ago
    Reading this discussion (and posting a comment about s-expressions) got me reading about Lisp[1], and then wondering about contemporary Lisp implementations, and then to Arc where I found this amusing comment by our host: "Object-oriented programming generates a lot of what looks like work. Back in the days of fanfold, there was a type of programmer who would only put five or ten lines of code on a page, preceded by twenty lines of elaborately formatted comments. Object-oriented programming is like crack for these people: it lets you incorporate all this scaffolding right into your source code." http://www.paulgraham.com/noop.html http://www.paulgraham.com/noop.html [1] I was paid to program in Common Lisp for about 6 years. However, this was a while ago so I was attempting to refresh my memory.
  - slurgfest 14y ago
    What is interesting about reading this discussion is that all of the 'examples' used in order to show that comments are bad are totally implausible. On the other side, the situation of 'no comments at all' is actually ubiquitous, in reality. Writing out what you are doing takes a little work, and requires at least briefly thinking about it. It also means you can be embarrassed if your code is doing something irrational or unintended, and looking at everything again when you make major breaking changes. By Occam's Razor, it seems more likely that complaining about comments is driven by an unwillingness to produce them more than actual practical problems created for others by their presence.
- deleted 14y ago
  [deleted]
arethuza 14y ago
I tend to get a bit upset if code has comments that basically just describe what code is doing rather than why. Stuff along the lines of: // Increment the total total++; // Execute our SQL query var result = query.execute(); Seems to happen a lot with developers who use comments to "sketch out" code (not a bad thing) and then leave the comments in place when the actual code is written.
- flatline3 14y ago
  I prefer code where I can skim the comments and see the major plot points, at a glance.
  - dllthomas 14y ago
    If you need to skim the comments to see how a function is doing what it's doing, the function is too long.
    - flatline3 14y ago
      When it can take 3-4 statements to perform a single logical operation, there is still value in summarizing each block with a comment, even if the function isn't "too long".
      - gnaritas 14y ago
        That's what function names are for. Comments don't need to summarize. A useful comments says why code is this way, it doesn't summarize or repeat code.
        flatline3 14y ago
        > That's what function names are for. A single function for every 3-4 line operation would result in incredibly disjointed code, and would require more explicit documentation of invariants because that function can now be called elsewhere (at least inside of the given translation unit). > A useful comments says why code is this way, it doesn't summarize or repeat code. That's nonsensical. Why wouldn't you want to abstract the complex?
flatline3 14y ago
> I've met a few senior level programmers who frown on detailed commenting (or commenting at all). If they express those views, I wouldn't call them senior. Commenting is necessary to express invariants, and to summarize complexity that would otherwise require each reader of the code to understand the code itself in depth. Those are actually closely related things. Very few languages are capable of succinctly expressing sufficiently detailed invariants. Some are better than others -- maybe they support Maybe monads instead instead of possibly-NULLs. However, it's rarely possible to express -- purely in code -- what the code is supposed to do, what the input is supposed to be, and what the output is supposed to be. Failing to express those things means that any future reader/maintainer will be forced to trace your code, in its entirety, to reverse-engineer how it is probably supposed to work. In many cases said maintainer can never know for sure without tracing your code and ALL code that calls your code -- otherwise, any change to that code could break undocumented behavior that other code relies upon. Anyone who advocates against comments is justifying laziness, and they're wrong. The only supportable argument for not commenting is if a language is sufficiently powerful and succinct enough to express all the invariants normally expressed through comments, as well as being readable enough to permit a future maintainer to understand the design of the code without requiring them to spend an undue amount of time studying its inner mechanics. I'm not aware of such a programming language.
- Ralith 14y ago
  Dependently typed programming languages can do the "express all the invariants" bit. Readability is an open question, though.
- rimantas 14y ago
  “Don’t comment bad code—rewrite it.” —Brian W. Kernighan and P. J. Plaugher Is that senior enough for you? > Anyone who advocates against comments is justifying > laziness, and they're wrong No, they are actually advocating to put more effort in thinking about stuff: how you name your functions/methods/whatever, how do you name your arguments/parameters, how do you write the code itself. To anyone interested I recommend to get a copy of "Clean Code" and read the relevant chapter. IIRC "Code Complete" mostly agrees.
julsonl 14y ago
The issue I have with commenting is some people enforce it for the sake of having comments in place, which would most of the time describe the "what" and the "how" of the code, rather than the "why", which in my opinion, where most of the value lies. In Java, the usual offenders would be the getter and setters in POJOs, like: * Returns the name * @return the name */ public String getName();
- flatline3 14y ago
  Comments like that exist simply to appease documentation tools that can't derive those comments automatically. The net gain is that you get nice API documentation. The downside is that you have a verbose and obvious comment in the source.
- slurgfest 14y ago
  Aren't such comments usually autogenerated by the IDE or such tools?
ucee054 14y ago
The problem is not when programmer (A) writes the code and the comments correctly. Nor when jackass(B) updates the code and not the comments, making them misleadingly worse than no comments at all. But when the code now has to be maintained by programmer (C). This means you.
wanderr 14y ago
The only thing worse than uncommented code, is wrongly-commented code. In my experience, code is almost always wrongly-commented, either because the programmer wrote the comment wrong in the first place, or because they wrote the code wrong, or because the code was later updated to do something different, and the comment was not updated to reflect the changes. In my experience, especially in an old codebase, it's extremely rare to find a piece of code that is both thoroughly and accurately commented. Given that reality, I would rather forego the comments for readable code. Readable code tells me what is going on, and doesn't lie!
einhverfr 14y ago
In my considered experience, those who are most hostile to unnecessary comments tend to put the most comments in their code. It isn't an argument against code comments, just being very picky about what is a useful comment collaboration-wise.

wreckimnaked 14y ago

There's some debate on this: http://queue.acm.org/detail.cfm?id=1053354 http://queue.acm.org/detail.cfm?id=1053354

creativename 14y ago

I feel like there are some people who go overboard on the formalities of commenting (specific format, etc.), but in general I can't think of one instance where I've thought "man, I wish I (or someone else) hadn't spent time explaining what this does". I even find that when I write comments to explain what a specific method is intended for, it helps me avoid violating the single-responsibility principle. If I clearly spell out what I'm trying to accomplish, it helps keep me focused. To those who say that the code should be elegant enough to be read on its own, there are some cases where the business logic involved is really what needs to be explained. At the same time, what is elegant and concise for you may appear obfuscated and confusing for someone else. You may argue that they should know all the techniques that you know, but that's just the reality of working with others sometimes.

lawn 14y ago
> I can't think of one instance where I've thought "man, I wish I (or someone else) hadn't spent time explaining what this does". There are good uses of comments, but there are also bad ones. From Coding Horror [1] an example: '************************************************* ' Name: CopyString ' ' Purpose: This routine copies a string from the source ' string (source) to the target string (target). ' ' Algorithm: It gets the length of "source" and then copies each ' character, one at a time, into "target". It uses ' the loop index as an array index into both "source" ' and "target" and increments the loop/array index ' after each character is copied. ' ' Inputs: input The string to be copied ' ' Outputs: output The string to receive the copy of "input" ' ' Interface Assumptions: None ' ' Modification History: None ' ' Author: Dwight K. Coder ' Date Created: 10/1/04 ' Phone: (555) 222-2255 ' SSN: 111-22-3333 ' Eye Color: Green ' Maiden Name: None ' Blood Type: AB- ' Mother's Maiden Name: None ' Favorite Car: Pontiac Aztek ' Personalized License Plate: "Tek-ie" '************************************************* Now imagine something like this exists for every function and you're reading the source code... Annoying. Others are less extreme of course, but repeating the code in comments is bad and even harmful if you forget to update the comment as well as the code. DRY is a good principle to have. Of course "all comments are bad" is simply wrong, comments are essential to explain decisions or non-obvious snippets or gotchas.
- creativename 14y ago
  Yeah, that's exactly the kind of formality and over-commenting that I meant by "I feel like there are some people who go overboard on the formalities of commenting (specific format, etc.)". I saw a lot of examples of that at my old employer where they had tried (and failed) to automate some of their documentation years and years ago. It's nice to have a brief description of what a class (or in many cases, a method) is intended for, etc. As others have said, it saves time each successive programmer from having to fully understand all of the source code.
  - lawn 14y ago
    Ah I see, misunderstood a bit.
- arethuza 14y ago
  Reading this discussion (and posting a comment about s-expressions) got me reading about Lisp[1], and then wondering about contemporary Lisp implementations, and then to Arc where I found this amusing comment by our host: "Object-oriented programming generates a lot of what looks like work. Back in the days of fanfold, there was a type of programmer who would only put five or ten lines of code on a page, preceded by twenty lines of elaborately formatted comments. Object-oriented programming is like crack for these people: it lets you incorporate all this scaffolding right into your source code." http://www.paulgraham.com/noop.html http://www.paulgraham.com/noop.html [1] I was paid to program in Common Lisp for about 6 years. However, this was a while ago so I was attempting to refresh my memory.
- slurgfest 14y ago
  What is interesting about reading this discussion is that all of the 'examples' used in order to show that comments are bad are totally implausible. On the other side, the situation of 'no comments at all' is actually ubiquitous, in reality. Writing out what you are doing takes a little work, and requires at least briefly thinking about it. It also means you can be embarrassed if your code is doing something irrational or unintended, and looking at everything again when you make major breaking changes. By Occam's Razor, it seems more likely that complaining about comments is driven by an unwillingness to produce them more than actual practical problems created for others by their presence.
deleted 14y ago
[deleted]

arethuza 14y ago

I tend to get a bit upset if code has comments that basically just describe what code is doing rather than why. Stuff along the lines of: // Increment the total total++; // Execute our SQL query var result = query.execute(); Seems to happen a lot with developers who use comments to "sketch out" code (not a bad thing) and then leave the comments in place when the actual code is written.

flatline3 14y ago
I prefer code where I can skim the comments and see the major plot points, at a glance.
- dllthomas 14y ago
  If you need to skim the comments to see how a function is doing what it's doing, the function is too long.
  - flatline3 14y ago
    When it can take 3-4 statements to perform a single logical operation, there is still value in summarizing each block with a comment, even if the function isn't "too long".
    - gnaritas 14y ago
      That's what function names are for. Comments don't need to summarize. A useful comments says why code is this way, it doesn't summarize or repeat code.
      - flatline3 14y ago
        > That's what function names are for. A single function for every 3-4 line operation would result in incredibly disjointed code, and would require more explicit documentation of invariants because that function can now be called elsewhere (at least inside of the given translation unit). > A useful comments says why code is this way, it doesn't summarize or repeat code. That's nonsensical. Why wouldn't you want to abstract the complex?

flatline3 14y ago

> I've met a few senior level programmers who frown on detailed commenting (or commenting at all). If they express those views, I wouldn't call them senior. Commenting is necessary to express invariants, and to summarize complexity that would otherwise require each reader of the code to understand the code itself in depth. Those are actually closely related things. Very few languages are capable of succinctly expressing sufficiently detailed invariants. Some are better than others -- maybe they support Maybe monads instead instead of possibly-NULLs. However, it's rarely possible to express -- purely in code -- what the code is supposed to do, what the input is supposed to be, and what the output is supposed to be. Failing to express those things means that any future reader/maintainer will be forced to trace your code, in its entirety, to reverse-engineer how it is probably supposed to work. In many cases said maintainer can never know for sure without tracing your code and ALL code that calls your code -- otherwise, any change to that code could break undocumented behavior that other code relies upon. Anyone who advocates against comments is justifying laziness, and they're wrong. The only supportable argument for not commenting is if a language is sufficiently powerful and succinct enough to express all the invariants normally expressed through comments, as well as being readable enough to permit a future maintainer to understand the design of the code without requiring them to spend an undue amount of time studying its inner mechanics. I'm not aware of such a programming language.

Ralith 14y ago
Dependently typed programming languages can do the "express all the invariants" bit. Readability is an open question, though.
rimantas 14y ago
“Don’t comment bad code—rewrite it.” —Brian W. Kernighan and P. J. Plaugher Is that senior enough for you? > Anyone who advocates against comments is justifying > laziness, and they're wrong No, they are actually advocating to put more effort in thinking about stuff: how you name your functions/methods/whatever, how do you name your arguments/parameters, how do you write the code itself. To anyone interested I recommend to get a copy of "Clean Code" and read the relevant chapter. IIRC "Code Complete" mostly agrees.

julsonl 14y ago

The issue I have with commenting is some people enforce it for the sake of having comments in place, which would most of the time describe the "what" and the "how" of the code, rather than the "why", which in my opinion, where most of the value lies. In Java, the usual offenders would be the getter and setters in POJOs, like: * Returns the name * @return the name */ public String getName();

flatline3 14y ago
Comments like that exist simply to appease documentation tools that can't derive those comments automatically. The net gain is that you get nice API documentation. The downside is that you have a verbose and obvious comment in the source.
slurgfest 14y ago
Aren't such comments usually autogenerated by the IDE or such tools?

ucee054 14y ago

The problem is not when programmer (A) writes the code and the comments correctly. Nor when jackass(B) updates the code and not the comments, making them misleadingly worse than no comments at all. But when the code now has to be maintained by programmer (C). This means you.

wanderr 14y ago

The only thing worse than uncommented code, is wrongly-commented code. In my experience, code is almost always wrongly-commented, either because the programmer wrote the comment wrong in the first place, or because they wrote the code wrong, or because the code was later updated to do something different, and the comment was not updated to reflect the changes. In my experience, especially in an old codebase, it's extremely rare to find a piece of code that is both thoroughly and accurately commented. Given that reality, I would rather forego the comments for readable code. Readable code tells me what is going on, and doesn't lie!

einhverfr 14y ago

In my considered experience, those who are most hostile to unnecessary comments tend to put the most comments in their code. It isn't an argument against code comments, just being very picky about what is a useful comment collaboration-wise.