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

[Matthew Knepley]

On Thu, Sep 22, 2011 at 12:14 AM, Jed Brown <jedbrown at mcs.anl.gov> wrote:

> 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".
>

I originally did this and Barry vetoed using another suffix.

   Matt

-- 
What most experimenters take for granted before they begin their experiments
is infinitely more interesting than any results to which their experiments
lead.
-- Norbert Wiener
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.mcs.anl.gov/pipermail/petsc-dev/attachments/20110922/9207b3f2/attachment.html>