Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

I've never seen a language's style guide recommend avoiding comments before

haskell.org

Post reply on HN
Print view View original

101–110 of 198 posts

Re: I've never seen a language's style guide recommend avoiding comments before

#101

Post by nirvdrum »

brazzy wrote: post #95
nirvdrum wrote: post #87

Earlier quoted context omitted.

Yes. The industry is full of hacks. I don't see how that's a problem with comments though. They're going to write hideous code with or without comments.

The problem is that comments visually bloat the code and make it harder to understand. Bad code with useless comments is worse than bad code with no comments. And that's not even counting comments that are out of date and misleading...

And bad code with good comments is more useful than bad code with no comments. It strikes me that replacing "comments" with "tests" in much of our thread would lead to the same outcome. I guess we're just going in circles on this one.

Re: I've never seen a language's style guide recommend avoiding comments before

#102

Post by wtetzner »

rotten wrote: post #61

Of course everyone thinks they always write good clean code and therefore don't need comments to elaborate on what the heck is going on. Unfortunately, having been doing this trade for 30+ years, I've found most people write crappy code in a hurry to try to hit some deadline based on incomplete requirements and confusing business rules. A few precious comments stuck in there can help the next guy, months or years lat…

> Style guides that eschew comments, IMO, are counterproductive. They feed on the developer's ego and disregard reality.

To be fair, the style guide that's linked to doesn't actually say not to write comments. It says that if you're going to write a comment, think twice. Maybe you can make the code clearer instead.

Re: I've never seen a language's style guide recommend avoiding comments before

#104

Post by nmrm »

seanmcdirmid wrote: post #47
bnegreve wrote: post #14

This is not convincing to me because the examples are trivial: -- swap the elements of a pair swap :: (a,b) -> (b,a) Yes this is redundant. let b=a+1 -- add one to 'a' Yes this is also redundant Does it mean that every piece of code can be expressed as clearly as in a one-line comment in natural language? I don't think so.

But you see, nobody on the internet has ever offered up examples of good comments before, at least that I can find. So if you say these comments are bad, but there exists good comments, why not provide examples of good comments to make your argument stronger?

What about the Code Complete examples posted somewhere on this thread? ("above", at the moment)?

What about checkable specifications together with a comment explaining the formula, particularly for anything with a nice physical intuition? This kind-of addresses the out-of-date comment problem.

Another example which came to mind is a Lamport comment about some sort of layout-related thing, I can't remember specifics. The comment gives a really good intuitive feel for why his code produces a nice-looking layout. Without the physical intuition provided by the comment, the code is pretty difficult to grok. I can't find it, so I really hope I'm not making this up...

edit: 2nd par

Re: I've never seen a language's style guide recommend avoiding comments before

#105

Post by seanmcdirmid »

notduncansmith wrote: post #94
seanmcdirmid wrote: post #59

Earlier quoted context omitted.

Often only with a deep understanding of the complex problem to understand its simplicity. But you have to ship in 4 weeks, so why not just get something working first?

Because simpler code usually leads to less bugs, which is faster and cheaper than complex, buggy code.

I find that the better I understand a problem, the simpler code I can solve with it. But I can also understand the problem better by solving it with code, and repeat a few times for a few months to approach an ideal solution.

Writing simpler code is more expensive than writing complicated code for that reason, unless you are a genius who can simplify any complex problem instantaneously. Anyways, your argument basically amounts to "do good, no do bad."

Re: I've never seen a language's style guide recommend avoiding comments before

#106

Post by reitanqild »

seanmcdirmid wrote: post #63
rotten wrote: post #61

Of course everyone thinks they always write good clean code and therefore don't need comments to elaborate on what the heck is going on. Unfortunately, having been doing this trade for 30+ years, I've found most people write crappy code in a hurry to try to hit some deadline based on incomplete requirements and confusing business rules. A few precious comments stuck in there can help the next guy, months or years lat…

> Comments cost essentially nothing to add to your code and can save it from an early death and complete refactoring by the next guy who comes along. Whatever their benefits are, this is not true at all. Comments are expensive to write and maintain. They are VERY VERY expensive to maintain because there is no automated way to test them.

Disagree.

Reason: In Software Archeology (a.k.a. maintaining legacy code) you are often happy to get any kind of clue as to what went on inside someones head. Maybe they saw an edge case?

Of course you should write self-documenting code with variables and function names that explains most of it but when you either have to

1. factor out a new function

do_this_to_fix_that_weird_thing(weird state)

or

2. have to add a line

state == weird ? fix = fix+1:continue // weird is a weird state that sometimes occurs even though vendors api docs says otherwise.

please think twice.

Outdated comments are a problem but very often a problem I'll happily deal with compared to not having them at all. If a comment doesn't make sense you can also try checking VC history.

Re: I've never seen a language's style guide recommend avoiding comments before

#107

Post by ktzar »

koonsolo wrote: post #17

Comments say what your code does, your code says how you do it. The swap example is trivial, but for most functions it is good to add an API comment, because how you use the function shouldn't depend on how it's implemented, but what it should do, described in the comment. That way you can change your implementation as long as you don't change the contract. In other words, changing how your code does something should…

As another commenter said above, comments shouldn't say "what" your code does, but "why" you do it,... when you need an explanation. There's no better comment of what code does that code itself.

Re: I've never seen a language's style guide recommend avoiding comments before

#108

Post by _pmf_ »

blowski wrote: post #29

Avoiding comments that do what your code should be doing is common practice, and I think that's what this style guide is recommending. Comments are useful to describe __why__ you're doing something, often when you are not able to change the unexpected behaviour. Whenever I build an API library, my code is littered with comments like "Acme Corp API requires this happens before that" with a link to that bit of the API…

That's the only thing that must be said about this topic.

As a rule of thumb, if I've thought more than 20 seconds about what a particular section of code has to do, I comment it.

Re: I've never seen a language's style guide recommend avoiding comments before

#109

Post by why-el »

denizozger wrote: post #55

Robert C. Martin's Clean Code book has a great section on comments: - The proper use of comments is to compensate for our failure to express ourself in code. Comments are always failures. We must have them because we cannot always figure out how to express ourselves without them, but their use is not a cause for celebration. So when you find yourself in a position where you need to write a comment, think it through a…

This actually works even in natural language. If you think about it for a moment, sometimes what you thought isn't necessarily what you said, and most likely you will, either intentionally or unintentionally, resort to other means to communicate the thought, such as facial expressions, what you are wearing, and so on.

I think it's a common fallacy to believe that it is our failure when we can't express a particular thought. The language itself, be it human or the far more restrictive and qualitatively restrained computer version, is deficient in many regards.

Re: I've never seen a language's style guide recommend avoiding comments before

#110

Post by nirvdrum »

seanmcdirmid wrote: post #60
rtpg wrote: post #52

Earlier quoted context omitted.

comments might diverge from behaviour but the code, almost by definition (modulo some crazy magic happening/broken interpreter ) _is_ the behaviour.

The best commenting system is a debugger stepping through the code. Unfortunately, I've yet to see a commenting style that is able to really document mental models about how the code works.

SEURAT is a research project that attempted this. I was a test subject for it a while back and found it pretty interesting. But its implementation at the time was an Eclipse plugin that probably hasn't been kept up todate. You can find a paper on it on the ACM digital library:

http://dl.acm.org/citation.cfm?id=1368215

I'm sure the dissertation is available somewhere on cs.wpi.edu, too.

Post reply on HN