List:Internals« Previous MessageNext Message »
From:Sergey Vojtovich Date:April 8 2009 12:38pm
Subject:[style] inconsistency in Commenting Code section + proposed a new
section "Keep The Code Clean"
View as plain text  
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
Thread
[style] inconsistency in Commenting Code section + proposed a newsection "Keep The Code Clean"Sergey Vojtovich8 Apr
  • Re: [style] inconsistency in Commenting Code section + proposed a newsection "Keep The Code Clean"Ingo Strüwing8 Apr
  • Re: [style] inconsistency in Commenting Code section + proposed a newsection "Keep The Code Clean"Konstantin Osipov26 Jun