On Tuesday, January 6, 2015, Peter Kelly <[email protected]> wrote: > > On 7 Jan 2015, at 1:26 am, Dennis E. Hamilton <[email protected] > <javascript:;>> 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).
This is not really coding standard but git usage, but its ok for me if we mix it all. rgds jan i > > > 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] <javascript:;> > > 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) > > -- Sent from My iPad, sorry for any misspellings.
