Positional cues or not

[Manuel M. T. Chakravarty]

"Marcin 'Qrczak' Kowalczyk" <mk167280@zodiac.mimuw.edu.pl> wrote,

> 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