[Ns-developers] coding style and code reviews update

[Tom Henderson]

We've had some on-list and off-list discussion about how the ns-3 code
reviews are going, and about the use and possible changes to the coding
style guidelines.

Regarding the coding style, Mathieu has suggested to tighten it up by
aligning with current codebase conventions and applying the extended
rules to new code submissions.  Over time, there have been small
discussions about vagueness in the coding style, and whether we are
being too rigorous or too loose in enforcing it (opinions vary).

In my opinion, if you scan our current codebase, you will see that the
application of our coding style and engineering guidelines is uneven,
and to avoid years of exceptions piling up on us, we would probably be
well served by revisiting the existing coding style document and
updating it and considering to bring new submissions more into alignment
(and possibly our existing codebase).

Of course, this has the potential for discouraging contributors, so we
should explore whether some automated scripts or programs can be used to
bring code into alignment.  We ought to also better flag what are hard
requirements vs. looser guidelines, and also to document what are
engineering guidelines or conventions that we try to enforce.  In short,
an approach where we try to avoid surprises in the review process (by
more explicitly documenting our rules and guidelines) and where we
provide tools for users to bring their code into alignment, may strike
the right balance between maintainers and contributors.

I took a pass at the coding style document and uploaded it to Rietveld
to allow people to comment on it and discuss it using that tool:

http://codereview.appspot.com/165087/show

if you want to track discussion on this document, please follow the
ns-3-reviews group discussion.

If you want a nicely formatted version, please see this page:
http://www.nsnam.org/~tomh/codingstyle/codingstyle.html

Another topic is how the reviews are going.  In general, I think that
the reviews have been very important and have improved the submissions
in all cases, and I appreciate the many hours that maintainers and
contributors have spent on them.  However, we ought to avoid surprises
and avoid requests to rewrite code late in the review process.  I wrote
down a new section in our code-submission.html document that attempts to
explain the rationale of ns-3 code reviews, and tries to suggest ways to
avoid surprises and resolve disagreements.  I also put these proposed
changes into the tracker (and a formatted sample) here:

http://codereview.appspot.com/165087/show
http://www.nsnam.org/~tomh/codingstyle/code-submission.html (under the
"ns-3 code reviews" heading)

Your comments or feedback on these proposed revisions would be welcome.

- Tom