From HaskellWiki
Revision as of 11:28, 30 December 2010 by Lemming (talk | contribs) (initial thoughts)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

It is generally a good idea to write comprehensible programs, and adding comments to your program can help to achieve that goal. However it is not true that every program can be become comprehensible by adding enough comments. In the first place you should write as clearly as possible such that comments are not necessary. If you are going to write a comment, think about the following before you actually write it:

  • Is it a comment that documents unexpected behaviour? Then better avoid the unexpected behaviour. Example:
a+b-b  -- you cannot delete (b-b) because the operations are not associative

If the operations are not associative for your custom type, then better do not define a Num instance for it. (Sure, Float types are not ideal.)

  • Is it an obvious comments? Example:
-- swap the elements of a pair
swap :: (a,b) -> (b,a)

Congratulations: You have chosen a function name and a type signature that make the purpose of the function pretty without any comment. Thus: omit the comment, you only risk that it becomes out of sync with the function.

  • Does the comment duplicate the Haskell report?

See also