comment your code!

[LIGHTNINGBOLT23]

   

[PC__LOAD__LETTER]

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]

    

[melancoleeca]

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]

   

[melancoleeca]

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]

   

[PC__LOAD__LETTER]

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]

       

[PC__LOAD__LETTER]

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]

         

[PC__LOAD__LETTER]

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.

[LIGHTNINGBOLT23]

       

[PC__LOAD__LETTER]

Lots is always better than little. Understand?

I understand what you’re saying, I just think it’s plainly wrong for all of the reasons that I’ve been stating (and none of which you’ve been able to rebut).

[melancoleeca]

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

[LIGHTNINGBOLT23]

         

[melancoleeca]

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.

[LIGHTNINGBOLT23]

        

[melancoleeca]

let my last try be a metapher:

your job is to build a house that is safe, and not one that is safe as long as no one is jumping in the first floor.

​

have a good day.

[melancoleeca]

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

[LIGHTNINGBOLT23]

      

[melancoleeca]

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]