6 ms·

> 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

> 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.

macintux 8y ago
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 8y ago
  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.
  - macintux 8y ago
    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 8y ago
      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.
  - TeMPOraL 8y ago
    > 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 8y ago
      Centralized comment references sounds like a good+simple idea - I'll try to remember it, and hope I never have to of course ;-).
      - TeMPOraL 8y ago
        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.
- tengbretson 8y ago
  If a function is only a few lines long its action should be entirely documented by its name.
  - macintux 8y ago
    The action, sure, but there’s more context than that in many cases. See my other comment. https://news.ycombinator.com/item?id=18773167 https://news.ycombinator.com/item?id=18773167
vvanders 8y ago
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.
- icebraining 8y ago
  Which is the first iteration, the code or the comment?
- majikandy 8y ago
  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 8y ago
  > I've seen horrible inheritance/convoluted refactors done in pursuit of DRY. Everything in moderation, including moderation itself.
lazyjones 8y ago
> 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 8y ago
  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 8y ago

macintux 8y ago

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 8y ago
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.
- macintux 8y ago
  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 8y ago
    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.
- TeMPOraL 8y ago
  > 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 8y ago
    Centralized comment references sounds like a good+simple idea - I'll try to remember it, and hope I never have to of course ;-).
    - TeMPOraL 8y ago
      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.
tengbretson 8y ago
If a function is only a few lines long its action should be entirely documented by its name.
- macintux 8y ago
  The action, sure, but there’s more context than that in many cases. See my other comment. https://news.ycombinator.com/item?id=18773167 https://news.ycombinator.com/item?id=18773167

vvanders 8y ago

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.

icebraining 8y ago
Which is the first iteration, the code or the comment?
majikandy 8y ago
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 8y ago
> I've seen horrible inheritance/convoluted refactors done in pursuit of DRY. Everything in moderation, including moderation itself.

lazyjones 8y ago

> 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 8y ago
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 8y ago