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

111–120 of 198 posts

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

#111

Post by AlisdairO »

seanmcdirmid wrote: post #98
anthracis417 wrote: post #72

Earlier quoted context omitted.

Forgive my ignorance, but why and how would you test a comment? They don't do anything, there is no instruction for the machine to understand or run.

The comments are meant to be read and used to understand code. So you must test them like any other artifact to ensure that they are a net positive and not a net negative. Programmers make mistakes, which hopefully fail a test or at least cause a crash. Because comments can't be executed, neither of those will happen; they have to be verified manually

Isn't that fairly easy to do during a code review?

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

#112

Post by dscrd »

duncan_bayne wrote: post #2

I've always treated comments as code smells. Not necessarily something bad, but something that at least suggests the possibility of suboptimal code. One of the best cases for comments IMO is documenting an unexpected behaviour on the part of a third-party API. But even then, correct exception / error-handling code can obviate the need for comments in many cases. If I'm reading code (from an experienced programmer) an…

Remember your gas mask if you ever check out literate programming...

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

#113

Post by kabdib »

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…

I'll add comments to already existing bad code, describing the results of my archeology.

I should refactor. But sometimes it's not feasible when you're in a hurry and the area has no unit tests to prop it up. Adding a tag "TODO: CLEANME" or something similar works as a reminder.

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

#114

Post by ARussell »

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…

It seems to me that the Haskell wiki's recommendations on commenting align pretty well with Uncle Bob's. Personally, I'm glad for this. On this topic, I agree with both Uncle Bob and the Haskell wiki.

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

#115

Post by Ixiaus »

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…

The point of Haskells type system though is that those annotations tell you most if not all of those things, they're a form of documentation that is very powerful and designing your types clearly makes it even better.

Plus your annotations are updated! Comments wither and die.

[Edit] to be clear, if there is something going on that would cumbersome to "document with types" i just write comments. There's also a place for function description and example.

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

#116

Post by Confusion »

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…

  A few precious comments stuck in there can help the next 
  guy [..]
More than spending that time on improving the code?

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

#117

Post by ARussell »

SchizoDuckie wrote: post #91

The thing with comments is: You should add them for people that don't want to read your code line by line. I don't want to run my internal compiler in my head when i'm reading your code, so you better make sure there's at least a docblock above every function that describes in 2 sentences what it does so I can get a global overview of what the heck this file is doing. People that suggest that 'the code is the documen…

That is exactly why once should take the time to give meaningful names to their functions, classes, and methods. If you are having a difficult time doing it, your piece of code is probably doing too much. Split it into pieces that are more easy to name.

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

#118

Post by SchizoDuckie »

shabbyrobe wrote: post #97

I see rubbish like this in PHP (and Java) code all the time: /** * Frobnicates a foobar * * @param Foobar $foobar The foobar to be frobnicated * @param int $intensity The intensity with which the foobar will * be frobnicated (defaults to 4) * @return mixed The result of frobnicating a foobar */ function foobar_frobnicate(Foobar $foobar, $intensity=5) { // frobnicates the foobar return $foobar->frobnicate($intensity);…

I think we can all agree that this is the most blatant example of useless documentation.

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

#119

Post by AlisdairO »

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…

> Programmers can’t realistically maintain them.

Why not? The effort involved is not very high.

If you mean that they won't maintain them, well, I agree. Sometimes I fail to do so myself - but that's my laziness, not because keeping a comment up to date is actually difficult. The fact that programmers can be lazy is why we put processes in place to catch ourselves - code reviews, code style enforcement, and so on.

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

#120

Post by nahname »

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…

How can you write clean, simple comments if you cannot write clean, simple code.
Post reply on HN