Friday, March 5, 2010

Hash or dash?

I am pleased to say that SBI (Sysel Bootstrap Interpreter) is making good progress. You can already create object instances, play with the variadic built-in function Exec, raise and handle exceptions, etc.

Now I know you might think I am just being silly, but I still haven't decided on how to write comments. Basically I am oscillating between hash (as you saw in previous posts) and dash (--), i.e. double hyphen, for denoting comments.

Hash is easier for me to type, because I can type hash with my left hand and use arrow keys with my right hand at the same time. For double hyphen I either need to use the little finger of my right hand, or lift the hand and move it towards the minus key.

From aesthetic point of view... I just don't know. Most of the time I seem to prefer dash, although it clashes with the bullet point hyphens in the BSD license in the HelenOS format (but an alternative form could be used for that).

What I am quite confident with is that the commonly used comments should be single-line comments, where comments blocks would be created by typing in a series of single-line comments. Multi-line comments would only be used for disabling sections of code (typically for debugging purposes).

Doc-blocks will be started by a special single-line comment (such as ## or ---) and continued by regular single-line comments (such as # or --).

An interesting idea here pertains to the way of denoting the 'brief' part of the doc block. The common methods include: (1) up to the first period (.), (2) the first paragraph, (3) the first paragraph if marked with some special tag (such as @brief). Another way which came to my mind is that if the 'brief' part spanned more than one line, all these lines would use the same doc-comment mark. Example:

## First line of doc brief and
## this is the second line.
# This is no longer part of
# the brief.


--- First line of doc brief and
--- this is the second line.
- This is no longer part of
- the brief.

Do you like one of these comment styles better than the other? If so, why? Or would you recommend yet another one? Let's hear ye!


  1. I must say I like the multi-dash comments. The series of dashes seems to "fade out" the comment in a natural way.

    With a single dash, wouldn't this be a problem when I wrap a rather long arithmetic expression before the minus operator, such as in this example:

    a = 1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + 9
    - b

  2. Terminology issue... I never meant to propose a single ASCII minus/hyphen '-', but two or three (like in Ada/VHDL).

    When I say dash I mean the double (or triple) minus. (Dash is much longer than minus or hyphen an is often rendered as '--' in ASCII (for en-dash) or sometimes even --- for em-dash.)

  3. OK, it was a bug in the code :-) It should have been:

    --- First line of doc brief and
    --- this is the second line.
    -- This is no longer part of
    -- the brief.