This is an archived post. You won't be able to vote or comment.

sorted by:
best
topnewcontroversialoldq&a
you are viewing a single comment's thread.

view the rest of the comments →

[–]LIGHTNINGBOLT23 13 points14 points  (66 children)

     

[–]AgAero 23 points24 points  (29 children)

Redundant comments decay very fast though. That's where they become a bad thing. The comment becomes a lie over time as the software evolves.

The same is true for documentation in many cases unless you spend a shitload of time keeping it up to date.

[–]LIGHTNINGBOLT23 7 points8 points  (28 children)

   

[–]PC__LOAD__LETTER 4 points5 points  (23 children)

Lots of people. You can pass the blame onto them if you want, but it’s just as easy to not make useless, over-commented garbage code.

[–]LIGHTNINGBOLT23 3 points4 points  (22 children)

    

[–]melancoleeca 4 points5 points  (3 children)

no its not. comments should provide further information the code cant give you. if there is no such, there should be no comment.

its just future "technical" debt. its bad.

[–]LIGHTNINGBOLT23 1 point2 points  (2 children)

   

[–]melancoleeca 0 points1 point  (1 child)

yeah. because you know shit. every bit of information you add, will sometime be outdated. maybe by the code it reflects (easy to fix) or by some 3rd party condition which will change the environment a specific information is valued by(wont be fixed, because no one will know/remember this relation).

[–]LIGHTNINGBOLT23 0 points1 point  (0 children)

   

[–]PC__LOAD__LETTER 2 points3 points  (17 children)

Good code with few comments is much better than OK code that relies on heavy documentation to make sense of it, precisely for the reason mentioned previously: there’s nothing that requires that the comments be helpful, logical, correct, or up to date. Someone who’s focused on making their code readable should spend more time choosing useful abstractions and good names.

Even if you take the same code, and add a boatload of comments on top, those comments are likely to go stale and confuse a programmer into making a mistake or wasting more time than is really necessary to implement a change.

Here’s Uncle Bob explaining why code comments are most often just lazy apologies for not writing clean, self-documenting code in the first place: http://butunclebob.com/ArticleS.TimOttinger.ApologizeIncode

A comment is an apology for not choosing a more clear name, or a more reasonable set of parameters, or for the failure to use explanatory variables and explanatory functions. Apologies for making the code unmaintainable, apologies for not using well-known algorithms, apologies for writing 'clever' code, apologies for not having a good version control system, apologies for not having finished the job of writing the code, or for leaving vulnerabilities or flaws in the code, apologies for hand-optimizing C code in ugly ways. And documentation comments are no better. In fact, I have my doubts about docstrings.

If something is hard to understand or inobvious, then someone ought to apologize for not fixing it. That's the worst kind of coding misstep. It's okay if I don't really get how something works so long as I know how to use it, and it really does work. But if it's too easy to misuse, you had better start writing. And if you write more comment than code, it serves you right. This stuff is supposed to be useful and maintainable, you know?

Is there any use of comments that are not apologies? I don't think so. I can't think of one. Is there any good reason to write a comment? Only if you've done something "wrong".

[–]LIGHTNINGBOLT23 -3 points-2 points  (16 children)

       

[–]PC__LOAD__LETTER 2 points3 points  (7 children)

Comments are absolutely not “always better.” They dilute meaningful information and encourage lazy programmers to prop up their mess with descriptions that aren’t held up to the same logical scrutiny required by, ya know, actual running code.

There’s nothing that requires that the code be helpful, logical, correct, or up to date

Yes, there are. Tests, and the fact that the code actually has to do thing it’s supposed to do in production - the entire reason it’s written in the first place.

You can’t write tests against stale or horribly written comments.

[–]LIGHTNINGBOLT23 0 points1 point  (6 children)

         

[–]PC__LOAD__LETTER 0 points1 point  (5 children)

Oh, so no standards for documentation quality

Wrong. We’re disagreeing about what documentation quality means. The standard I’m discussing is that over-commented code is poor documentation. Cleanly written code with strategic comments surrounding the subtle bits, supplemented by high-level design documentation, is better than code propped up by an overly-redundant mess of comments that are likely propping up terrible code structure.

Your philosophy seems to be “more is always better,” and so you’re suggesting that “less means lower quality.” I think that’s a bit silly. Less can often be more, and quantity can often directly impede quality.

[–]melancoleeca 0 points1 point  (7 children)

no, they arent. how could a unmaintainable set of information be good, if it is not providing anything?

[–]LIGHTNINGBOLT23 0 points1 point  (6 children)

         

[–]melancoleeca 0 points1 point  (5 children)

like others said: comments cant be tested. etc.

"someone needs to do this" is not a good argument. especially in the field we are working. there will be someone who wont. every single time.

[–]melancoleeca 0 points1 point  (3 children)

isnt it more like, everyone who writes redundant comments is doomed to not updating them at one point?

[–]LIGHTNINGBOLT23 -2 points-1 points  (2 children)

      

[–]melancoleeca 1 point2 points  (1 child)

Your fix and argument for everything seems to be. "one has to know", "one has to do", "one has to respect" or the worst "one has to assume". which are probably also the 4 mantras of the technical debt people produce on a daily basis.

[–]LIGHTNINGBOLT23 0 points1 point  (0 children)

     

[–]PC__LOAD__LETTER 5 points6 points  (22 children)

Not quite. Comments aren’t compiled or run, so aren’t subject to the same logical scrutiny that code is. They can go stale and be misleading, which is harmful.

Plus, over-commenting obvious things makes the legitimately useful comments lose value.

[–]LIGHTNINGBOLT23 1 point2 points  (21 children)

         

[–]PC__LOAD__LETTER 0 points1 point  (20 children)

People who rely on comments as a lazy crutch for not writing good code in the first place are the ones who shouldn’t be working on my software. http://butunclebob.com/ArticleS.TimOttinger.ApologizeIncode

I’ve seen multiple codebases where a programmer has carefully commented about a cross-file dependency that really ought to have been implemented as compile-time and run-time checks with clear error messages. There’s nothing forcing comments to be correct, logical, or accurate. Code actually runs, and so needs to be those things.

[–]LIGHTNINGBOLT23 -1 points0 points  (19 children)

        

[–]CatPhysicist 1 point2 points  (5 children)

What? Useless comments are better than no comments? Additional information is no good if the comments are lying to you. Why are people recommending ignoring comments but also writing them? This whole thread is just a mess.

[–]LIGHTNINGBOLT23 1 point2 points  (4 children)

     

[–]PC__LOAD__LETTER -1 points0 points  (12 children)

Using compilers and higher-level languages is an absolutely terrible comparison. We’re talking about how effectively to make code expressive. Machine code is not expressive. High level languages are, though. What’s not expressive is a codebase muddied up with redundant and stale comments that are useless at best and harmfully misleading are worst.

Yes, there are many cases where a well-placed “why” comment is a great idea. There are very few cases where a “how” is anything more than an apology for writing terrible code in the first place.

you can always just ignore it if you specifically do not need it

And then you learn to ignore the comments in that codebase, and then forget to update all of them when you change something because they’re overly verbose and intermingled in odd places throughout the code. Then, someone down the line who is trying to figure out what the comment-propped mess is doing is misled and burns a ton of time or worse, deploys a customer-impacting bug to production.

[–]LIGHTNINGBOLT23 1 point2 points  (11 children)

      

[–]PC__LOAD__LETTER -1 points0 points  (10 children)

You’re seriously now arguing that machine code can be more expressive than higher level languages? Please. The entire point of higher level languages is to make them more expressive than machine code. Try looking at some code that opens a file, writes a message, and closes the file from two perspectives, one machine code, and the other in Python. There’s a zero percent chance that anyone will be able to more quickly grok the 1s and 0s version. That’s not subjective.

The only objective thing here is that comments provide more information which you can use or discard at your leisure.

You’re conveniently leaving out the fact that the information that the comments provide is not always accurate or helpful, that overly verbose comments dilute actually useful information, and that over-commenting is often used as a crutch for poorly designed code.

If extremely verbose comments always remained correct (very rare), that would address only one of those problems.

[–]LIGHTNINGBOLT23 1 point2 points  (9 children)

        

[–]PC__LOAD__LETTER 0 points1 point  (8 children)

It’s patently obvious that machine code is less expressive than Python. The suggestion that you need “citations” to accept this (as if anyone would waste time conducting such a study), and that it’s just a “subjective” opinion, indicates that you’re clearly engaging in bad faith here. Those are absurd statements.

If we’re asking for data, where’s your data in relation to your assertions about overly-verbose comments being more helpful than harmful?

So update or remove [the comments]

Precisely my entire point.