[josteink]

> do other HNers also feel that a high comment:code ratio probably indicates quality?

I consider it a big risk of errors.

When some code is changed, will all related comments be rewritten too? I doubt it.

And then you end up with a codebase which indicate A but comments which clearly spell out B, and you as a maintainer have no idea what to believe.

DRY. Don’t repeat yourself. The comments should not double up for the code. That’s just future maintenance nightmare.

[vvanders]

I've seen horrible inheritance/convoluted refactors done in pursuit of DRY.

I'm a bigger fan of WET(Write Everything Twice). Usually the first iteration of a component you don't understand enough of the domain space to get the abstractions right. So use that first attempt to explore the issues/problems/corner cases. Once well understood, rewrite it into something concise and well abstracted.

I've also find that if you try to re-write a third time you'll end up being to clever in trying to predict where a system will evolve and get you right back into the same situation as the first iteration.

[majikandy]

Commonly referred to as rule of 3. Write it out in full twice, on the 3rd time it must be a real abstraction, therefore refactor.

[josteink]

> I've seen horrible inheritance/convoluted refactors done in pursuit of DRY.

Everything in moderation, including moderation itself.

[icebraining]

Which is the first iteration, the code or the comment?

[lazyjones]

> And then you end up with a codebase which indicate A but comments which clearly spell out B, and you as a maintainer have no idea what to believe.

Can you name a few examples where you encountered this? In my career (30 years programming) I've never seen it. I believe it's a common, poor excuse for not writing enough comments.

The benefits of comments are well-understood. For me personally they often helped compensate sloppy code, (non-obvious) assumptions and prevented bad solutions because I reconsidered while writing (embarrassing) comments.

when you have to maintain a large codebase modified thousands of times in 15+ years, every single comment is invaluable.

[tigershark]

Then you must have been very lucky, I have seen it happening probably hundreds of times in a mere 15 years on the job. The inconsistencies that I experienced ranged from doc strings stating to pass a parameter that didn’t exist any more, parameters with different names, parameters with the correct names but in different orders. As per actual comment I have seen plenty of time comments like

    //here we go baby!
    //do not touch!
    //1 ... //2 ... //3 .. //8

The last one apparently was to indicate the order of some overengineered stuff that could have been written properly.

//This happens only for CompletedOrders (while in reality it was the opposite)

//This calculates the notional in the same currency (while it was converting it in GBP)

//This is extremely important, never delete (and after that there was a bunch of commented code)

Honestly I don’t remember all of them, I tend to use my memory for more important things, but I bet that if you had seen only 1/10 of the bad comments that I have encountered you would have a different opinion. Btw in your post you are explaining exactly why I hate comments:

“For me personally they often helped compensate sloppy code” - the solution is obviously to fix the sloppy code, not to write a comment because you are too lazy to fix it

“(non-obvious) assumptions” - this is probably the only legitimate reason to write a comment.

“and prevented bad solutions because I reconsidered while writing (embarrassing) comments.” - this has nothing to do with the comments given that at the end you didn’t write it. Thinking more about the code instead of trying to comment it gives you the same result, if not even better.

[lazyjones]

I was asking specifically about comments that directly contradict the code in a way that confuses the reader. If obsolete comments like "never delete" stand before commented code, what makes you think the commented code is actually used or useful?

> “(non-obvious) assumptions” - this is probably the only legitimate reason to write a comment.

If that's what you think, I rest my case...

[majikandy]

Are you serious? Almost every codebase that has comments has code that doesn’t exactly match the comments. Main obvious reason being that the comments aren’t executed whereas the code is. Sure meticulous attention to detail could keep the two in the sync. But you are suggesting that they have always been in sync for any code you’ve looked at?

As someone who is clearly a fan of comments, are you saying you’ve never modified a comment to make it more accurate to what the code is doing?

[macintux]

Short functions help here.

If every function is just a few lines long, the comments are easier to keep synchronized, and if a function drops out of service, it should eventually be garbage collected with its now-irrelevant comments.

[emn13]

But what if comments pertain to unexpected states the system as a whole can be in?

Kind of the whole problem is when there are weird corner cases going on that straddle function boundaries.

I'm not saying that's a good thing; mind you - but nor is it always trivially avoidable, especially if code needs to be concurrency and/or exception safe -- or in general whenever the statements your function consists of have surprising and opaque behavior based on system state, particularly if said state is hard to grasp due to being implicit or dynamic, or simply large and complex.

[TeMPOraL]

> Kind of the whole problem is when there are weird corner cases going on that straddle function boundaries.

If the problem has "hub and spokes" topology, i.e. it's relevant to multiple places in code that all reference a single location, put a comment describing the issue in that single location, and everywhere else put a comment with a reference. //Warning. See comment in [that location].

If there's no single best place for the detailed comment, put it in some design notes file, and put a comment with a reference to that file in all the affected places.

DRY can, and should be, applied to comments as well.

[emn13]

Centralized comment references sounds like a good+simple idea - I'll try to remember it, and hope I never have to of course ;-).

[TeMPOraL]

Yeah, references to a centralized document is such an obvious thing... once you read about it. It's another thing I recently picked up from Ousterhout's book, and looking back, I can now see the places in past codebases where I wish I thought of that myself.

[macintux]

Agreed, but that’s why I prefer writing code that has no global state. In Erlang, for example, it’s unusual (and the language lends itself via pattern matching to having short function clauses).

It gets a little tiresome threading the relevant state to every function that needs it, but it’s worthwhile in the end.

[emn13]

Even a pure function has "state" - namely its (arbitrarily complex) inputs. But sure, it's a little less of a landmine.

The fundamental issue remains that sometimes your knowledge about that state (whether the classical kind or a proper parameter) can be complex and dependent on what happened elsewhere, especially if the codebase your in was grown into that situation, and not designed like that per-se. A comprehensible set of preconditions and postconditions isn't always a luxury you have, certainly not at first.

[tengbretson]

If a function is only a few lines long its action should be entirely documented by its name.

[macintux]

The action, sure, but there’s more context than that in many cases. See my other comment.

https://news.ycombinator.com/item?id=18773167