Note that this isn't the "official" Haskell style guide. We don't have one (although we probably shouldn't). This is one of the competing guides out there.
I've never seen a language's style guide recommend avoiding comments before
21–30 of 198 posts
Re: I've never seen a language's style guide recommend avoiding comments before
#22There's similar advice in the Ruby Style Guide - https://github.com/bbatsov/ruby-style-guide#no-comments
Comments often go out-of-sync with the code, so I think it makes a lot of sense to prefer writing comprehensible code instead of trying to explain with comments something totally incomprehensible.
Re: I've never seen a language's style guide recommend avoiding comments before
#23I'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…
One case of unexpected behavior which is best described in comments is when the simple and obvious solution to the problem is wrong, and has already been discarded.
(Preferably the reasons for discarding the simple solution should be provided as well, as circumstances may change.)
Re: I've never seen a language's style guide recommend avoiding comments before
#24I totally agree with this. I like to put a bigger comment block at the top of my source files explaining the overall concepts and data structures used and then put few actual comments in the code. Instead I think about my variables and function names and make them talk for them-self. Commenting each and every element of your code will just make people (possibly yourself) curse at you when debugging your code and real…
I generally sympathise with your sentiment - I think this jives fairly well with comments talking about 'why' rather that 'what'. I do favour function-level comments quite a bit for more complex functions.
That said, I think some of the commenters in this thread should spend time maintaining a MLOC+ sized code base before dismissing comments as 'code smell'. Even in well-written code, if you're a maintenance programmer who is unfamiliar with a particular functional area, a few comments talking about the overall purpose of the code and why it works the way it does can save you enormous amounts of time.
Finally, if people are letting comments go out of date, IMO they have a quality issue. Either the comments are useless and should be removed, or they're useful and should be kept up to date. If your developers are letting useful comment areas go out of date, it should get caught by code review.
Re: I've never seen a language's style guide recommend avoiding comments before
#25Comments are lousy for describing what you are doing, but there are no alternative to comments for describing why something is done.
Re: I've never seen a language's style guide recommend avoiding comments before
#26I'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
*/
Re: I've never seen a language's style guide recommend avoiding comments before
#27Comments 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…
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.
Re: I've never seen a language's style guide recommend avoiding comments before
#28There's similar advice in the Ruby Style Guide - https://github.com/bbatsov/ruby-style-guide#no-comments Comments often go out-of-sync with the code, so I think it makes a lot of sense to prefer writing comprehensible code instead of trying to explain with comments something totally incomprehensible.
It's weird to me how people will slate low quality code, but think it's okay (or inevitable) to let comments go out of date. If your comments aren't useful, delete them. If they are, keep them up to date. It's part of behaving responsibly towards the rest of your team just as much as writing readable code is.
Re: I've never seen a language's style guide recommend avoiding comments before
#29Avoiding 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 documentation.
Here's a C++ example about "documenting surpises" (taken from Steve McConnell's Code Complete:
for ( element = 0; element > 1;
}
/* The following code is necessary to work around an error in
WriteData() that appears only when the third parameter
equals 500. '500' has been replaced with a named constant
for clarity. */
if ( blockSize == WRITEDATA_BROKEN_SIZE ) {
blockSize = WRITEDATA_WORKAROUND_SIZE;
}
WriteData ( file, data, blockSize );
Re: I've never seen a language's style guide recommend avoiding comments before
#30I'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.