On Thu, Sep 22, 2011 at 12:14 AM, Jed Brown <span dir="ltr"><<a href="mailto:jedbrown@mcs.anl.gov">jedbrown@mcs.anl.gov</a>></span> wrote:<br><div class="gmail_quote"><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
Almost all compilers accept this, but the AIX IBM compilers do not. I just fixed a bunch of these in petsc-3.2.<div><br></div><div>1. NEVER use // style comments in C source.<br><div><br></div><div>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.</div>

<div><br></div><div>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:</div>

<div><br></div><div>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.</div>

<div><br></div><div>Note that there are lots of examples with huge swaths of commented-out dead code. These need to be fixed.</div></div><div><br></div><div>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.</div>

<div><br></div><div>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.</div>

<div><br></div><div>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.</div>

<div><br></div><div>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".</div>

</blockquote></div><br>I originally did this and Barry vetoed using another suffix.<div><br></div><div>   Matt<br clear="all"><div><br></div>-- <br>What most experimenters take for granted before they begin their experiments is infinitely more interesting than any results to which their experiments lead.<br>
-- Norbert Wiener<br>
</div>