Hi!
While reading coding guidelines I found out inconsistency in the
"Commenting Code" section.
We state that a comment is indented by two spaces:
<quot>
When writing multi-line comments please put the '/*' and '*/' on their
own lines, put the '*/' below the '/*', put a line break and a two-space
indent after the '/*', do not use additional asterisks on the left of
the comment.
</quot>
Whereas in the example, which is immediately following this sentence, we
use three spaces:
<quot>
/*
This is how a multi-line comment in the middle of code
should look. Note it not Doxygen-style if it's not at the
beginning of a code enclosure (function or class).
*/
</quot>
Below there is yet another example, which seem to be correct:
<quot>
/*
This is a standalone comment. The comment is aligned to fit 79
characters per line. There is a dot at the end of each sentence.
Including the last one.
*/
</quot>
Also I didn't find anything about whether spaces are allowed at the end
of the line and after function name (before arguments), e.g.:
- "<SP><SP><SP>" - empty line with spaces;
- "something<SP>" - a line with space at the end;
- "some_func<SP>(arg1, arg2)" - a space between function name and
arguments.
As you can see these extra spaces mostly do not affect code readability,
but they're rather trash.
As I'm seeing this pretty frequently, I think it would be nice to
documented it either in a new section or in the "Indentation and
Spacing" section.
Regards,
Sergey
--
Sergey Vojtovich <svoj@stripped>
MySQL AB, Software Engineer
Izhevsk, Russia, www.mysql.com
