Mailing-List: contact dev-help@corinthia.incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@corinthia.incubator.apache.org
Received-SPF: softfail (athena.apache.org: transitioning domain of
 dennis.hamilton@acm.org does not designate 216.234.124.51 as permitted
 sender)
Reply-To: <dennis.hamilton@acm.org>
From: "Dennis E. Hamilton" <dennis.hamilton@acm.org>
To: <dev@corinthia.incubator.apache.org>
Subject: Coding Standards page
Date: Tue, 6 Jan 2015 10:26:24 -0800
Organization: NuovoDoc
Message-ID: <005b01d029de$4819bff0$d84d3fd0$@acm.org>
MIME-Version: 1.0
Content-Type: text/plain;
	charset="UTF-8"
Content-Transfer-Encoding: quoted-printable
Thread-Index: AdAp2QHf0f0FyH7NS/OspFsxwS7SRw==
Content-Language: en-us
Received-SPF: softfail (supercp.com: domain of transitioning
 dennis.hamilton@acm.org does not designate 97.113.57.118 as permitted sender)

I am looking at this page: =
<http://corinthia.incubator.apache.org/policy_coding.html>.

Here are some random remarks.  I don't want to touch the material =
without some discussion of what is important on this page.

I notice there are a number of editorial remarks that don't give much =
light into what the conventions are.  I would remove most of that.

The general rule for open-source contributions is to honor the style =
that is used in the code.  Here is a too-rambling description of K&R =
style, <http://en.wikipedia.org/wiki/Indent_style#K.26R_style>.

The use of white space is important and that has to be spelled out =
because it is not obvious when looking at the code.

I would separate out code formatting from other aspects of contributions =
(such as tests, etc.).  Code formatting is pretty low level and =
contributions, inclusion of tests, etc., are at a different level of =
practice.

I notice that the requirement for Unix line endings is not included, nor =
is there information on how to control that when working with the =
repository.

I also notice that we've not said anything about comments and also if =
any documentation-extraction conventions are being applied. =20

There is also, with this Apache project, the standard rules for the ASF =
Copyright headers.

Oh, and C++ dependencies.  I assume that all function entry points are =
CDECL, yes?  If that is the case, the use of Corinthia APIs from C++ =
code need to reflect the extern "C" business.

INCLUDE STATEMENTS

I don't understand the prohibition of #include in header files.  Is =
there a technical reason for this? =20

An obvious occasion for nested #include cases is when a header defines =
some sort of structure or function prototype that depends on some types =
that are defined in other headers.  The obvious place to handle the =
dependency is in the header that needs those to be defined.

This does raise conventions for assuring that headers are not processed =
repeatedly.  (We should also not be depending on precompiled headers.  =
That is an old hack that no longer makes sense and has become a =
meaningless ritual.)