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!
