corinthia-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Peter Kelly <pmke...@apache.org>
Subject Re: Coding Standards page
Date Tue, 06 Jan 2015 18:44:06 GMT
> On 7 Jan 2015, at 1:26 am, Dennis E. Hamilton <dennis.hamilton@acm.org> wrote:
> 
> 
> 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.

Agreed.

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

Yes - we need to state this and also explain how this can be enforced with a git configuration
option (something I haven’t had a chance to look into yet).

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

On this - what is the correct way to mention contributors here? Currently the header files
all say "Copyright 2012-2014 UX Productivity Pty Ltd” but this needs to be changed to recognise
the copyrights of other contributors to the project. If you can point me to info about what
the expected practice here I’ll be happy to take care of this (a separate contributors file?),
and I should be able to change all the files fairly quickly with a sed script.

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

We should have the cdecl thing in the public API most definitely - the library should be usable
by C++. I would argue it’s unnecessary in the source files and library-private header files,
at least if we’re going to stick to C for the implementation language.

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

Neither do I.

Jan can speak to this better than I can, but I think the rationale behind it was to avoid
exposing too many functions in the code, so we can keep low-coupling between different parts
of the code.

My take is that an include file should contain #includes for everything that it needs. For
example, let’s say we have a header file Foo.h that includes a number of functions which
return a value of type size_t. Foo.h should then have, at minumum, #include <stddef.h>,
or if necessary some other file that includes it.

Similarly, if we have one of our own data structures, say OPCPackage, then any header file
containing functions that use this type should also include the header where OPCPackage is
defined. Now this doesn’t necessarily have to be the “class header” as such (which defines
all the “member functions” of the OPCPackage “class”); as long as it’s a header
which includes a typedef.

In all of the “classes” I’ve created, I have typedef struct Foo Foo; somewhere in the
code, usually the “class header”. However at Jan’s suggestion (which I agree with) I
started moving some of those to a separate header file - you can have a look at OOXMLTypedefs.h
and see a bunch of typedefs. As long as a header includes another header which has all the
typedefs for types it uses, that’s necessary.

I think it’s important however that when you include a header file in a source file, then
you only need to include that header - not others. Otherwise we end up having to modify a
large number of source files if we want to add a new function declaration to a file that uses
a new type.

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

I should learn to read mails in their entirety before starting to respond :)

The standard #ifdef guard avoids repeated processing, and is already used in all the headers.
We should mention this in the coding conventions.

—
Dr Peter M. Kelly
pmkelly@apache.org

PGP key: http://www.kellypmk.net/pgp-key <http://www.kellypmk.net/pgp-key>
(fingerprint 5435 6718 59F0 DD1F BFA0 5E46 2523 BAA1 44AE 2966)


Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message