2. No blank lines
between the Doxygen comment and the function definition,
to make the assignment clear (if one blank line is above and
below [3], it
is not that clear if it belongs to the following definition).
I know this is a matter of personal preference, but I like the
blank lines around large blocks of comments. When there is no
space, I think it can be harder to separate the code from the
comments. OTOH, maybe that is less true now that most things that
display code do some kind of syntax highlighting. OTTH, whether
there is a blank line or not, Doxygen seems to know that these
blocks of comments apply to the next function and it also seems
fairly obvious to me.
Very easy to uncover a raft of different opinions here. I like the
line above, but not the line below. For me, the line above is the
same as would be present for any division between code blocks. But
if I a have a convention that a blank line creates divisions then I
don't want such a division at the bottom of the line of comments.
Instead, I want the comments cuddled with the code to which they
apply.
Also, I never have any practical problem distinguishing code from
comments because, even super old school text interfaces like Vim,
have syntax highlighting; The comments are in one color and the
code is in another, done.
--Rik
|