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

171–180 of 198 posts

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

#171

Post by dllthomas »

tveita wrote: post #71
icebraining wrote: post #27

Earlier quoted context omitted.

Well, this is Haskell we're talking about. Between the name, type signature and the fact that most functions are pure (so, no side-effects to describe), it's often obvious what they do.

Like ( ) :: Monoid m => m -> m -> m (^?) :: s -> Getting (First a) s a -> Maybe a As a Haskell beginner I didn't find it to be a particularly self-documenting language. Between the use of custom operators and point-free style you can write a lot of code without naming anything to give a hint about what you're doing.

Regarding the second, that sounds like lens. First of all, stay away from lens as a Haskell beginner :-P

But let's take a swing at it. We start with something of type (s). At the very end, we're left with something of type (Maybe a). Since we know nothing about the types (s) or (a), we need something to relate these to each other if the function is going to produce a (Maybe a) for us (unless it just always gives us Nothing).

There's a lot going on in that second argument, but we can clearly see that it's some type parameterized by (s) and (a), so it provides that connection. It "tells us how to get an (a) out of an (s) in a way that might fail" - which intuition is additionally helped along by the fact that the type so parameterized is called Getting.

There's a little more going on, and for that you'll need to dive into the (extensive) documentation for lens. One thing that is not going on is any side effects though. The operator section (^? foo) will take some (s) and turn it into some (Maybe a) based only on the information contained in that (s) and foo.

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

#172

Post by dllthomas »

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.

I agree with this, but I also think it's better if you can avoid the weird thing.

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

#173

Post by dllthomas »

AlisdairO wrote: post #111
seanmcdirmid wrote: post #98

Earlier quoted context omitted.

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?

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

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

#174

Post by orclev »

mathattack wrote: post #144
levosmetalo wrote: post #138

Earlier quoted context omitted.

TFA is not arguing against writing comments, it's arguing againts writing obvious and meaningless comments. I'd much prefer no have no comment to 'getA' method than full blown comment saying 'ruturns B', just because before refactoring method was called getB, and the comment was meaningless then, and wrong now.

In this sense, the article doesn't add much value. If you're just saying, "Avoid unnecessary comments" you're in the same state of truisms as "Write quality code" or "Try your best".

To be fair the article doesn't just say "avoid unnecessary comments" it actually gives some pretty concrete examples of less than ideal comments and ways in which you can make the need for a comment in that situation unnecessary. The TL:DR; of the article is essentially compile time errors are better than comments for preventing bugs so use the Type system if you can to encode your invariants rather than simply trying to document them in your code. That said, you can't always do that for various reasons so in that case it's perfectly reasonable to put comments in documenting that, but in that case at least try to capture the intent behind the code, not simply rehash the mechanics of how the code is accomplishing that. E.G. "returns a count of how many users have been flagged in the Foo system", instead of "returns user_foo_count".

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

#175

Post by dragonwriter »

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

> The problem is that comments visually bloat the code and make it harder to understand.

That's a good reason to avoid breaking up logical blocks of code with comments.

Its not a good reason not to comment.

> Bad code with useless comments is worse than bad code with no comments.

That's a good reason to have code review (which includes review of comments) to ensure that there is neither bad code nor useless (including out of date or misleading) comments.

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

#176

Post by Nursie »

icebraining wrote: post #30
Nursie wrote: post #20

I'm a big believer in function level comments in code, in a sort of doxygen-ish style (I write mostly C). It allows you to document the intended inputs and outputs of the function and state its purpose. This increases maintainability and reusability. Functions themselves should be short and written as a sequence of logical steps. I'm also a big fan of doing things right rather than just hacking until it works, which…

But the thing is, in C a geocoding function would probably receive two ints and return a string, while in Haskell you'd probably have a function of type "Location -> Address". The type system obviates much of the need for those comments.

Indeed, a solid type system would remove some of that need, in C it can be very important to document what precisely that pointer is pointing to. Is it a provided buffer, something allocated and returned? Multiple or single element? etc etc.

I'm guessing Haskell doesn't need that? A simple statement of purpose would still help though?

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

#177

Post by dragonwriter »

seanmcdirmid wrote: post #155
AlisdairO wrote: post #137

Earlier quoted context omitted.

Yes, what I mean is, if you're doing code review then there's virtually no additional cost - you're looking over the changes anyway. It doesn't matter that the process is manual if you're already doing it. If you're not doing code review, then you perhaps either have some organisational issues or you have coworkers who are sufficiently responsible that you can trust them to do basic code hygiene work like keeping com…

I think comments would be more difficult to review than code, since you'd have to carefully make sure they are meaningful by examining the code, without the context of the programmers involved. Alternatively, you could add comments during code review to document the review and basically redo the comments on each review...maybe. Comments also break flow and get in the way of code reading, but could probably just be hi…

> I think comments would be more difficult to review than code, since you'd have to carefully make sure they are meaningful by examining the code, without the context of the programmers involved.

Actually, that only makes them hard to review if you are trying too hard, which defeats the purpose of reviewing comments -- if it is hard to validate the utility of a comment without the context of the programmer involved, its a bad comment and needs, at a minimum, to be clarified.

After all, the whole point of a comment is to communicate information to a future person who lacks the context of the programmer involved.

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

#178

Post by Nursie »

kabouseng wrote: post #26
Nursie wrote: post #20

I'm a big believer in function level comments in code, in a sort of doxygen-ish style (I write mostly C). It allows you to document the intended inputs and outputs of the function and state its purpose. This increases maintainability and reusability. Functions themselves should be short and written as a sequence of logical steps. I'm also a big fan of doing things right rather than just hacking until it works, which…

I also like to add doxygen headers to functions, but have stopped adding the inputs and outputs. Refactorings causes the doxygen to go out of sync with the code. Currently I only do the following: /**@fn foobar * @brief Does foo */ -edit formatting

This is true, if you're lazy!

In C at least, I think it's important to specify whether we're expecting a pointer to a single element, a pointer to an array, if the pointer is an output, etc etc. A uint8_t* could be many things...

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

#179

Post by dragonwriter »

nmrm wrote: post #85
Boldewyn wrote: post #3

Earlier quoted context omitted.

The situation must be differentiated by language/environment. The suggestions for Haskell are certainly not bad. They hold, too, for many systems programming. For scientific coding, comments should align with the underlying theory for the code: “This implements matrix transposition with regard to ... as defined by ...”, so that next generations can align code with papers better. And when you’re in a wacky environment…

> 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 codes. Programmers often disdain domain knowledge beyond that which they already have found to be immediately relevant. Which is perfectly understandable -- there's a reason they chose to specialize in programming rather than as domain experts in whatever domain.

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

#180

Post by dragonwriter »

dllthomas wrote: post #173
AlisdairO wrote: post #111

Earlier quoted context omitted.

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

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 assumption is (or later becomes) false.

Of course, it would be useful to have a way to verify the information about the assumptions to see if they have become false, but that's not about validating the comment, that's about validating the code it comments, since if the assumption is false, it is quite likely that the code needs to change (and this may not be something that unit testing the local code can discover, as such comments often are not about correctness but about choosing a less-than-obvious alternative correct approach for optimization, or to work around a quirk of the code being called, etc.)

Post reply on HN