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

[Barry Smith]

   Satish,

      Please investigate how you can add to the petsc-dev repository at petsc.cs.iit.edu a checking stage that runs a python script on all repository updates and rejects ones that satisfy certain criteria. There must be some tool in hg to help handle this.

   Thanks


   Barry


On Sep 22, 2011, at 2:14 AM, Jed Brown 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".