corinthia-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Dennis E. Hamilton" <dennis.hamil...@acm.org>
Subject Coding Standards page
Date Tue, 06 Jan 2015 18:26:24 GMT
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.  

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?  

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






Mime
View raw message