corinthia-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jan i <j...@apache.org>
Subject Re: Coding Standards page
Date Tue, 06 Jan 2015 19:37:36 GMT
On Tuesday, January 6, 2015, Peter Kelly <pmkelly@apache.org> wrote:

> > On 7 Jan 2015, at 1:26 am, Dennis E. Hamilton <dennis.hamilton@acm.org
> <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
> pmkelly@apache.org <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.

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