> On 7 Jan 2015, at 1:26 am, Dennis E. Hamilton <[email protected]> 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 [email protected] 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)
