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.
or
--- 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!
I must say I like the multi-dash comments. The series of dashes seems to "fade out" the comment in a natural way.
ReplyDeleteWith 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
Terminology issue... I never meant to propose a single ASCII minus/hyphen '-', but two or three (like in Ada/VHDL).
ReplyDeleteWhen 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.)
OK, it was a bug in the code :-) It should have been:
ReplyDelete--- First line of doc brief and
--- this is the second line.
--
-- This is no longer part of
-- the brief.