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

181–190 of 198 posts

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

#181

Post by dspillett »

rtpg wrote: post #52
dspillett wrote: post #50

Earlier quoted context omitted.

I've always gone with the adage: if the comment and code do not agree, don't assume that either of them are correct. A bad description isn't just a problem in itself, it can indicate a worse problem sat waiting to jump out and bite as you walk by.

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

> code, almost by definition _is_ the behaviour.

Yes, but is it the intended and/or desired behaviour in all cases that the codepath in question will be expected to experience?

That is the problem, especially in code that deals with rare edge cases so is not run often, and/or covers many circumstances where it is right but is wrong for one set of inputs that no one thought to test before (or since that code last changes).

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

#182

Post by jdbernard »

knowaveragejoe wrote: post #86
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.

He's referring to the problem of comments becoming out of sync with the code they're referring to. Not everyone updates comments as they update code.

And those people deserve a special place of torment all their own. How hard is it really to update, or at least delete comments that are no longer relevant when you modify the code?

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

#183

Post by gms7777 »

couchand wrote: post #126
nirvdrum wrote: post #78

Earlier quoted context omitted.

Well, native language and programming languages aren't the same thing and you express yourself differently in them. That's basically a given. But comments are most useful when they explain why something is being done, not what's being done. The latter is usually simple to work out with even the most hideous code. But if I don't know what you were trying to do or why you did something in a particular way, seeing what…

native language and programming languages aren't the same thing and you express yourself differently in them Indeed. However, when developing software I'd expect that the responsibility is first to express yourself clearly in code and only second to express yourself in prose, which means if you're taking very much time to do the latter it's time that could be spent doing the former.

The idea is that if you do a little bit of the latter now, you will save yourself or someone else a lot of time doing the former later.

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

#185

Post by nrzuk »

otikik wrote: post #42
nrzuk wrote: post #38

Personally I have no problems with comments in code for complex functions etc. But pointless comments like this below drives me insane. // get the user $user = $this->getUser(); Times that by the thousands of lines in a project and you have one big headache!

> Personally I have no problems with comments in code for complex functions etc I hope you have a problem with complex functions. (They should be made as simple as possible).

Heard this argument a few times and mostly I do agree, but in certain scenarios I'm not willing to spend a whole day on some perfect code when I can do it in a hour with some comments explaining it.

My scenarios for this typically include: * Disposable project, eg prototyping an idea for a client * I have an impossible deadline and I'm on a fixed project rate, maybe I should have quoted more, who knows, it happens

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

#186

Post by dllthomas »

notduncansmith wrote: post #73
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…

Sometimes, comments are a justification. Sometimes you have to do things that seem like the wrong thing to when reading the code (like sending a POST request instead of a GET when a GET is clearly more appropriate, but you have to talk to a poorly-written API that will only respond to POSTs on that route). Comments help rationalize that decision for the next guy. I also find TODO comments quite helpful. It requires f…

If you're systematic about the syntax of your TODO comments, you can also 1) jump to them, 2) traverse them in order of priority, 3) automatically surface changes to the list of TODOs as comments in commit messages, and 4) use commit hooks to refuse to commit code with overly severe TODOs to certain branches.

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

#187

Post by notduncansmith »

dllthomas wrote: post #186
notduncansmith wrote: post #73

Earlier quoted context omitted.

Sometimes, comments are a justification. Sometimes you have to do things that seem like the wrong thing to when reading the code (like sending a POST request instead of a GET when a GET is clearly more appropriate, but you have to talk to a poorly-written API that will only respond to POSTs on that route). Comments help rationalize that decision for the next guy. I also find TODO comments quite helpful. It requires f…

If you're systematic about the syntax of your TODO comments, you can also 1) jump to them, 2) traverse them in order of priority, 3) automatically surface changes to the list of TODOs as comments in commit messages, and 4) use commit hooks to refuse to commit code with overly severe TODOs to certain branches.

I do 1) pretty frequently, and while I don't go so far as 4), I do use total TODO count as a heuristic from time to time.

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

#188

Post by notduncansmith »

DanBC wrote: post #88
augustl wrote: post #66

Earlier quoted context omitted.

I wonder where the idea comes from that people that write code that's hard to understand, will write comments that are easy to understand.

Good programmers sometimes have to do weird things. Leaving a note about that weird thing is probably a good idea.

In my experience:

A novice programmer will just do the weird thing (no comments).

An intermediate programmer will spend twice as much time as they should, trying to think of an elegant solution, before doing the weird thing anyways (and maybe leaving a comment).

A good programmer will just do the weird thing, leave a comment, and move on.

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

#189

Post by notduncansmith »

peaton wrote: post #146
AlisdairO wrote: post #124

Earlier quoted context omitted.

I think because most people find written english easier to produce than clean code. Comments have certainly aided me enormously in navigating very large, sometimes crufty, codebases.

I don't mean this negatively, but in my experience as a high schooler and in college, the programming crowd tended to be lacking in written (communication) skills. This is certainly a huge blanket statement, but for younger programmers today I think the stereotype has at least some truth.

There are some people whose code I'd be terrified to maintain, if their code/comments are anything like their text messages.
Post reply on HN