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

191–198 of 198 posts

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

#191

Post by dllthomas »

notduncansmith wrote: post #187
dllthomas wrote: post #186

Earlier quoted context omitted.

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.

Yeah, I've never got as far as 4. I do 1-3 on my main project at my day job.

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

#192

Post by mmhammer »

seanmcdirmid wrote: post #122
AlisdairO wrote: post #111

Earlier quoted context omitted.

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

Sure, code review is a very manual approach.

It's manual whether with a tool or without. We like using a tool because it automates the process. We find teams are more thorough in their reviews with a tool. We're also distributed, so it helps with collaboration too.

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

#193

Post by dllthomas »

dragonwriter wrote: post #180
dllthomas wrote: post #173

Earlier quoted context omitted.

Only when all comments only refer to local information. There is nothing to check that the comment in that other file that refers to this code was correctly updated. Some system of backrefs could handle this, of course, but I'm not aware of anything in use...

> Only when all comments only refer to local information. There is nothing to check that the comment in that other file that refers to this code was correctly updated. The only time a comment should refer to non-local information is to document an assumption or basis of the local code, which is still correct information about the local code as long as it is the assumption/basis of the local code, even if the assumpti…

I'm not sure I disagree. In practice, though, I certainly encounter comments communicating nonlocal information ("This is used in ..."), and of course these are the least likely to remain accurate. "All comments is local" is something we should start drumming into people - I don't think anyone ever said this to me explicitly.

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

#194

Post by dllthomas »

notduncansmith wrote: post #188
DanBC wrote: post #88

Earlier quoted context omitted.

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.

I somewhat agree, except possibly for the "should". I think that trying to think of an elegant solution (and then accepting that you can't, where appropriate) is an important learning process. Of course this depends on context; spending time on learning is sometimes inappropriate.

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

#195

Post by nmrm »

dragonwriter wrote: post #179
nmrm wrote: post #85

Earlier quoted context omitted.

> For scientific coding, comments should align with the underlying theory for the code 100x this. Scientific software should be held to a different set of standards than non-scientific software, primarily because you can probably not assume that your reading is familiar with the underlying domain.

> Scientific software should be held to a different set of standards than non-scientific software, primarily because you can probably not assume that your reading is familiar with the underlying domain. As someone who works as a programmer and system analyst dealing with code in a non-scientific business domain where I've also worked on the domain side, I don't think that this separates scientific code from any other…

I thought through this some, and your comment resonates -- it's not right to set aside scientific code from other code with a complicated domain.

But I think complicated program segments related to business practices etc. also deserves comments, even just "see spec xyz" or "see section 1.2.3 of code xyz" (similar to how you might say "See Smith et al. '14" in a scientific setting)

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

#196

Post by remon »

commandar wrote: post #148
remon wrote: post #131

Earlier quoted context omitted.

It's not always a matter of being able to write clean, simple code. In fact in my experience ability is hardly ever a factor. You may not have enough time, you may have to use complex counter-intuitive APIs, the business requirements might be unclear, the algorithm might have complex components that are hard to convert to easy to read code, etc. There are literally dozens of reasons why code might not be "clean and s…

I'm in a field (healthcare integration) where vendors constantly break spec or handle things in a quirky manner. The actual code I work with is fairly straightforward and easy to understand functionally. I can understand the what of pretty much any of the code my organization runs in short order. But the why is vital. This week I've implemented things for reasons I won't remember in six months. Simple, easy to unders…

My sentiments exactly.

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

#197

Post by notduncansmith »

dllthomas wrote: post #194
notduncansmith wrote: post #188

Earlier quoted context omitted.

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.

I somewhat agree, except possibly for the "should". I think that trying to think of an elegant solution (and then accepting that you can't, where appropriate) is an important learning process. Of course this depends on context; spending time on learning is sometimes inappropriate.

I agree with that. Perhaps more accurate phrasing would be "more time than the seasoned developer would have". Part of getting to the third stage is learning those types of lessons during the second stage - which only comes with experience.

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

#198

Post by knowaveragejoe »

jdbernard wrote: post #182
knowaveragejoe wrote: post #86

Earlier quoted context omitted.

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?

It's not that it's hard, it just may not be apparent that you need to do so.
Post reply on HN