[petsc-dev] Use of '//' comments in C source

[Jed Brown]

Almost all compilers accept this, but the AIX IBM compilers do not. I just
fixed a bunch of these in petsc-3.2.

1. NEVER use // style comments in C source.

2. We should do a nightly with super locked-down GCC settings and/or with
the funky AIX IBM compilers. Perhaps also add a commit hook that rejects any
patch containing '//' comments.

3. There are a few places where there is dead code just commented out. This
is totally confusing if it's not accompanied by a comment explaining why the
code is dead. I propose the following guideline:

If you want to comment out some code (even one line) for any reason, you
MUST write a comment explaining why it is commented out and use #if 0,
#endif to mark the code as inactive (instead of comments). This is
preferable to /* comments because the #if can be nested. So no source code
in comments, ever.

Note that there are lots of examples with huge swaths of commented-out dead
code. These need to be fixed.

4. Avoid leaving dead code in the source at all costs. If you need it later,
it's in the Hg history. During the debugging phase, you can, e.g. #define
PETSC_PTHREADCLASSES_DEBUG 0 and then use if (PTHREADCLASSES_DEBUG) {
debugging output; } if you need a manual toggle.

5. The comment marker /* must ALWAYS be followed by a space and */ must
always be preceded by a space. Comments with a character in those positions
are control characters for the documentation and fortran generators. This is
a common mistake, be sure to configure your editor to do this correctly.

6. If a code block inside a man page should contain a literal comment (e.g.
to suggest what the user should fill in), '//' must be used because /*
comments cannot be nested. This case is very rare.

7. Matt, can we please, please use *.cxx for ALL files that need a C++
compiler to build. There are still lots of clearly C++-only files, but that
just don't get compiled unless a C++ compiler is being used. This is
confusing because you have to check the makefile to tell which dialect is in
use. I don't see any advantage to doing it this way. It would be far better
if *.c meant "this source file conforms to the intersection of C89 and
C++98" and *.cxx meant "needs a recent C++ compiler".
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.mcs.anl.gov/pipermail/petsc-dev/attachments/20110922/907d468b/attachment.html>