Block Comments Are a Bad Idea

Re:Block Comments Are a Bad Idea by Athas on Wednesday October 11, 2017 @08:36AM (#15449221)

Line comments are no hindrance to documentation generation. Extracting the contents from a paragraph line comment is a rather simple regular expression[0]. Haskell almost exclusively uses line comments for documentation, and it works fine. You write it like this (the '|' is to indicate that it's a doc-comment):

    -- | Compute this and that.
    -- Parameter @x@ is the good one, and
    -- parameter @y@ is the bad one.
    --
    -- The function works well and runs in time
    -- proportional to $O(n**n**n**n)$.
    f x y = ...

[ Parent | on HN ]

Re:Block Comments Are a Bad Idea by stinos on Wednesday October 11, 2017 @09:47AM (#15449688)

Actually my point was mainly about the readability aspect, should have made that more clear: for me there usually still is a (slight) advantage in readability if every line is not prefixed. E.g. the code you show here looks rather cluttered to me. It doesn't mean it does to you of course, if you are used to it your brain just ignores those dashes. But mine doesn't, since I am not used to it. Though it would probably take me only a couple of days.

[ Parent | on HN ]