"Marcin 'Qrczak' Kowalczyk"
On Mon, 12 Feb 2001, John Meacham wrote:
Another reason to use a distinctive document style is that comments are often used to do things like block out unwanted code, or comment out blocks which are not needed in hugs say but are in ghc (under the presumption someone will go in and edit it later).
These are always {- -}. I would use end-of-line comments for all kinds of documentation.
We have more choices than the number of introducing dashes:
-- This is Manuel's style of comments. -- Note the empty comment below: -- foo :: Some -> Interesting -> Type
For example we could simply decide that a documentation comment must come just before the type signature, without intervening all-whitespace line. Comments for larger blocks of definitions have at least one empty line after them and would be skipped.
Thanks for putting forward my comment style :-) malcolm-hs@cs.york.ac.uk wrote,
Well, I frequently use end-of-line comments for blocking out dead code. And this often ends up in exactly the place where a documentation comment might occur, for instance:
myFunctionF x y z = -- map (g . unlines . f . lines . something) (z x) -- is this wrong? map (f . unlines . g . lines . something) (z x)
In fact, the full story of my comment style is a bit longer. I have a convention for internal comments (ie, those that are not part of the interface, but only apply to the implementation), too. To extend your example, I write them as follows -- This is Manuel's style of comments. -- Note the empty comment below: -- foo :: Some -> Interesting -> Type -- -- Below we use the zeta-tau implementation technique for -- Omega spaces, see Journal of Functional Programming, -- pp100, 2010. -- Again note the delimiting empty comments. I doubt that -- such comments would appear in a program by coincidence -- (ie, as part of commenting some code out). -- foo x y = ... Cheers, Manuel