You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@corinthia.apache.org by "Dennis E. Hamilton" <de...@acm.org> on 2015/01/06 19:26:24 UTC
Coding Standards page
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.)
Re: Coding Standards page
Posted by Svante Schubert <sv...@gmail.com>.
Am 08/01/15 um 12:28 schrieb Svante Schubert:
> Am 08/01/15 um 00:51 schrieb Dave Fisher:
>> On Jan 7, 2015, at 3:40 PM, Dennis E. Hamilton wrote:
>>
>>> -- replying below to --
>>> From: jan i [mailto:jani@apache.org]
>>> Sent: Wednesday, January 7, 2015 13:51
>>> To: dev@corinthia.incubator.apache.org; orcmid@apache.org
>>> Subject: Re: Coding Standards page
>>>
>>> On Wednesday, January 7, 2015, Dennis E. Hamilton <or...@apache.org> wrote:
>>>
>>>> PS: I have the SVN definitions for the ODF documents, and I need to update
>>>> them for the Microsoft Office documents. I assume that having these
>>>> binaries is all right in collections of test documents, so long as they are
>>>> not in the part of our repositories that represent released source code.
>>> It is OK to have binaries for test. Can you please add the right git
>>> attributes to the main test dir.
>>>
>>> <orcmid>
>>> I don't see a main test dir anywhere.
>>> If you know of specific file extensions for binary content that we have,
>>> please update the .gitattributes file at the repository root. I couldn't
>>> Find anything with a quick scan of the repository.
>>> (The SVN definitions are different and we don't use our SVN that way.)
>>> </orcmid>
>>>
>>> [ ... ]
>>>
>> Feel free to make use of the documents at https://svn.apache.org/repos/asf/poi/trunk/test-data/
>>
>> Fair warning about copying. In the last year someone complained that a document that belonged to them had been submitted by another person with a bug report. We removed the file with apologies.
>>
>> I would therefore recommend that these test documents get pulled in by reference to POI's repos.
>>
> The centralization of test documents, where some of them (like on
> feature coverage) could to be accessed on demand, downloaded and be
> cached locally, similar as to Maven's .m2 directory mechanism for
> artifact would be indeed a great step forward!
>
> I have a lot of test documents in the ODF Toolkit, the problem is more
> to sort them according to features and to keep the number small, but
> with a good coverage to keep the test duration short and efficient.
>
> Regards,
> Svante
>
Sorry, sent too quickly.
Hopefully sometimes in the future test documents of a file format are
becoming (optional) part of its SDK, even better becoming part of the
standard of the file format itself. Like regression tests would become
part of a standard to provide a measurement for feature coverage of an
application supporting that file format (at least from model
perspective, but not necessary rendering).
This ability would require not only the specification of the model of
the file format, but as well its convertibility (API). As we are
specifying at the moment the changes upon the ODF model
<https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=office-collab>
being used for change-tracking.
Regards,
Svante
Re: Coding Standards page
Posted by Svante Schubert <sv...@gmail.com>.
Am 08/01/15 um 00:51 schrieb Dave Fisher:
> On Jan 7, 2015, at 3:40 PM, Dennis E. Hamilton wrote:
>
>> -- replying below to --
>> From: jan i [mailto:jani@apache.org]
>> Sent: Wednesday, January 7, 2015 13:51
>> To: dev@corinthia.incubator.apache.org; orcmid@apache.org
>> Subject: Re: Coding Standards page
>>
>> On Wednesday, January 7, 2015, Dennis E. Hamilton <or...@apache.org> wrote:
>>
>>> PS: I have the SVN definitions for the ODF documents, and I need to update
>>> them for the Microsoft Office documents. I assume that having these
>>> binaries is all right in collections of test documents, so long as they are
>>> not in the part of our repositories that represent released source code.
>> It is OK to have binaries for test. Can you please add the right git
>> attributes to the main test dir.
>>
>> <orcmid>
>> I don't see a main test dir anywhere.
>> If you know of specific file extensions for binary content that we have,
>> please update the .gitattributes file at the repository root. I couldn't
>> Find anything with a quick scan of the repository.
>> (The SVN definitions are different and we don't use our SVN that way.)
>> </orcmid>
>>
>> [ ... ]
>>
> Feel free to make use of the documents at https://svn.apache.org/repos/asf/poi/trunk/test-data/
>
> Fair warning about copying. In the last year someone complained that a document that belonged to them had been submitted by another person with a bug report. We removed the file with apologies.
>
> I would therefore recommend that these test documents get pulled in by reference to POI's repos.
>
The centralization of test documents, where some of them (like on
feature coverage) could to be accessed on demand, downloaded and be
cached locally, similar as to Maven's .m2 directory mechanism for
artifact would be indeed a great step forward!
I have a lot of test documents in the ODF Toolkit, the problem is more
to sort them according to features and to keep the number small, but
with a good coverage to keep the test duration short and efficient.
Regards,
Svante
Re: Coding Standards page
Posted by Dave Fisher <da...@comcast.net>.
On Jan 7, 2015, at 3:40 PM, Dennis E. Hamilton wrote:
> -- replying below to --
> From: jan i [mailto:jani@apache.org]
> Sent: Wednesday, January 7, 2015 13:51
> To: dev@corinthia.incubator.apache.org; orcmid@apache.org
> Subject: Re: Coding Standards page
>
> On Wednesday, January 7, 2015, Dennis E. Hamilton <or...@apache.org> wrote:
>
>> PS: I have the SVN definitions for the ODF documents, and I need to update
>> them for the Microsoft Office documents. I assume that having these
>> binaries is all right in collections of test documents, so long as they are
>> not in the part of our repositories that represent released source code.
>
> It is OK to have binaries for test. Can you please add the right git
> attributes to the main test dir.
>
> <orcmid>
> I don't see a main test dir anywhere.
> If you know of specific file extensions for binary content that we have,
> please update the .gitattributes file at the repository root. I couldn't
> Find anything with a quick scan of the repository.
> (The SVN definitions are different and we don't use our SVN that way.)
> </orcmid>
>
> [ ... ]
>
Feel free to make use of the documents at https://svn.apache.org/repos/asf/poi/trunk/test-data/
Fair warning about copying. In the last year someone complained that a document that belonged to them had been submitted by another person with a bug report. We removed the file with apologies.
I would therefore recommend that these test documents get pulled in by reference to POI's repos.
Regards,
Dave
Re: Coding Standards page
Posted by jan i <ja...@apache.org>.
On 8 January 2015 at 20:39, Dave Fisher <da...@comcast.net> wrote:
>
> On Jan 8, 2015, at 3:10 AM, jan i wrote:
>
> > On 8 January 2015 at 00:40, Dennis E. Hamilton <de...@acm.org>
> > wrote:
> >
> >> -- replying below to --
> >> From: jan i [mailto:jani@apache.org]
> >> Sent: Wednesday, January 7, 2015 13:51
> >> To: dev@corinthia.incubator.apache.org; orcmid@apache.org
> >> Subject: Re: Coding Standards page
> >>
> >> On Wednesday, January 7, 2015, Dennis E. Hamilton <or...@apache.org>
> >> wrote:
> >>
> >>> PS: I have the SVN definitions for the ODF documents, and I need to
> >> update
> >>> them for the Microsoft Office documents. I assume that having these
> >>> binaries is all right in collections of test documents, so long as they
> >> are
> >>> not in the part of our repositories that represent released source
> code.
> >>
> >> It is OK to have binaries for test. Can you please add the right git
> >> attributes to the main test dir.
> >>
> >> <orcmid>
> >> I don't see a main test dir anywhere.
> >> If you know of specific file extensions for binary content that we
> have,
> >> please update the .gitattributes file at the repository root. I
> >> couldn't
> >> Find anything with a quick scan of the repository.
> >> (The SVN definitions are different and we don't use our SVN that way.)
> >> </orcmid>
> >>
> >> My bad, I have one in my branch but it is not in the repo....I think
> went
> > away because peter moved test cases into docFormats, since they were all
> > white box testing.
> >
> > We need a test dir at top level for black box tests, please create one.
> May
> > I suggest we add the poi test documents in a subdir, with a readme file
> > that informs the origin.
> >
> > Dave@ thanks for your idea, and for sharing your concern...I think it is
> > better to have them in our git repo, so developers dont need multiple
> > version control clients.
>
> Keep in mind that some of these documents are examples of bad documents.
> It would be necessary to look into POI's unit tests. Having bad documents
> is good.
+1 just like in the real world it is the bad ones that break your bones.
However when we do testing, we should have some sort of naming scheme (or
directory structure) so we know what is bad and what is good.
rgds
jan i.
>
> Regards,
> Dave
>
> >
> > rgds
> > jan i
> >
> >> [ ... ]
> >>
> >>
>
>
Re: Coding Standards page
Posted by Dave Fisher <da...@comcast.net>.
On Jan 8, 2015, at 3:10 AM, jan i wrote:
> On 8 January 2015 at 00:40, Dennis E. Hamilton <de...@acm.org>
> wrote:
>
>> -- replying below to --
>> From: jan i [mailto:jani@apache.org]
>> Sent: Wednesday, January 7, 2015 13:51
>> To: dev@corinthia.incubator.apache.org; orcmid@apache.org
>> Subject: Re: Coding Standards page
>>
>> On Wednesday, January 7, 2015, Dennis E. Hamilton <or...@apache.org>
>> wrote:
>>
>>> PS: I have the SVN definitions for the ODF documents, and I need to
>> update
>>> them for the Microsoft Office documents. I assume that having these
>>> binaries is all right in collections of test documents, so long as they
>> are
>>> not in the part of our repositories that represent released source code.
>>
>> It is OK to have binaries for test. Can you please add the right git
>> attributes to the main test dir.
>>
>> <orcmid>
>> I don't see a main test dir anywhere.
>> If you know of specific file extensions for binary content that we have,
>> please update the .gitattributes file at the repository root. I
>> couldn't
>> Find anything with a quick scan of the repository.
>> (The SVN definitions are different and we don't use our SVN that way.)
>> </orcmid>
>>
>> My bad, I have one in my branch but it is not in the repo....I think went
> away because peter moved test cases into docFormats, since they were all
> white box testing.
>
> We need a test dir at top level for black box tests, please create one. May
> I suggest we add the poi test documents in a subdir, with a readme file
> that informs the origin.
>
> Dave@ thanks for your idea, and for sharing your concern...I think it is
> better to have them in our git repo, so developers dont need multiple
> version control clients.
Keep in mind that some of these documents are examples of bad documents. It would be necessary to look into POI's unit tests. Having bad documents is good.
Regards,
Dave
>
> rgds
> jan i
>
>> [ ... ]
>>
>>
Re: Coding Standards page
Posted by jan i <ja...@apache.org>.
On 8 January 2015 at 00:40, Dennis E. Hamilton <de...@acm.org>
wrote:
> -- replying below to --
> From: jan i [mailto:jani@apache.org]
> Sent: Wednesday, January 7, 2015 13:51
> To: dev@corinthia.incubator.apache.org; orcmid@apache.org
> Subject: Re: Coding Standards page
>
> On Wednesday, January 7, 2015, Dennis E. Hamilton <or...@apache.org>
> wrote:
>
> > PS: I have the SVN definitions for the ODF documents, and I need to
> update
> > them for the Microsoft Office documents. I assume that having these
> > binaries is all right in collections of test documents, so long as they
> are
> > not in the part of our repositories that represent released source code.
>
> It is OK to have binaries for test. Can you please add the right git
> attributes to the main test dir.
>
> <orcmid>
> I don't see a main test dir anywhere.
> If you know of specific file extensions for binary content that we have,
> please update the .gitattributes file at the repository root. I
> couldn't
> Find anything with a quick scan of the repository.
> (The SVN definitions are different and we don't use our SVN that way.)
> </orcmid>
>
> My bad, I have one in my branch but it is not in the repo....I think went
away because peter moved test cases into docFormats, since they were all
white box testing.
We need a test dir at top level for black box tests, please create one. May
I suggest we add the poi test documents in a subdir, with a readme file
that informs the origin.
Dave@ thanks for your idea, and for sharing your concern...I think it is
better to have them in our git repo, so developers dont need multiple
version control clients.
rgds
jan i
> [ ... ]
>
>
RE: Coding Standards page
Posted by "Dennis E. Hamilton" <de...@acm.org>.
-- replying below to --
From: jan i [mailto:jani@apache.org]
Sent: Wednesday, January 7, 2015 13:51
To: dev@corinthia.incubator.apache.org; orcmid@apache.org
Subject: Re: Coding Standards page
On Wednesday, January 7, 2015, Dennis E. Hamilton <or...@apache.org> wrote:
> PS: I have the SVN definitions for the ODF documents, and I need to update
> them for the Microsoft Office documents. I assume that having these
> binaries is all right in collections of test documents, so long as they are
> not in the part of our repositories that represent released source code.
It is OK to have binaries for test. Can you please add the right git
attributes to the main test dir.
<orcmid>
I don't see a main test dir anywhere.
If you know of specific file extensions for binary content that we have,
please update the .gitattributes file at the repository root. I couldn't
Find anything with a quick scan of the repository.
(The SVN definitions are different and we don't use our SVN that way.)
</orcmid>
[ ... ]
Re: Coding Standards page
Posted by jan i <ja...@apache.org>.
On Wednesday, January 7, 2015, Dennis E. Hamilton <or...@apache.org> wrote:
> I have added an appropriate (I hope) .gitattributes file to the Corinthia
> repository.
Looks real good to me.
>
> For SVN, it is necessary to make local changes to adjust line-endings
> cross-platform. The relevant ASF file for this is at <
> http://www.apache.org/dev/svn-eol-style.txt>.
thanks forgot about that page, will remember to give it to dorte.
>
> It turns out I have a custom one of these *and* it is in effect. The
> problem was I had replaced the rules for *.html and *.htm with ones that
> specified the MIME type and removed the svn:eol-style attribute, thinking
> it didn't matter. My bad. I did that years ago! (June 2011) It does
> matter for DIFF and for what others think the "right" line ending is.
>
> I have fixed that in my local SVN settings.
>
> PS: I have the SVN definitions for the ODF documents, and I need to update
> them for the Microsoft Office documents. I assume that having these
> binaries is all right in collections of test documents, so long as they are
> not in the part of our repositories that represent released source code.
It is OK to have binaries for test. Can you please add the right git
attributes to the main test dir.
thanks in advance
jan i
ps. we need a lot of test documents, would you and dorte be interested in
defining that work? I mis a good idea how to group it, how much in each
document etc.
>
> - Dennis
>
> -----Original Message-----
> From: Dennis E. Hamilton [mailto:dennis.hamilton@acm.org <javascript:;>]
> Sent: Tuesday, January 6, 2015 12:48
> To: dev@corinthia.incubator.apache.org <javascript:;>
> Subject: RE: Coding Standards page
>
>
>
> -- replying below to --
> From: jan i [mailto:jani@apache.org <javascript:;>]
> Sent: Tuesday, January 6, 2015 11:38
> To: dev@corinthia.incubator.apache.org <javascript:;>
> Subject: Re: Coding Standards page
>
> On Tuesday, January 6, 2015, Peter Kelly <pmkelly@apache.org
> <javascript:;>> wrote:
>
> > > On 7 Jan 2015, at 1:26 am, Dennis E. Hamilton <dennis.hamilton@acm.org
> <javascript:;>
> > <javascript:;>> wrote:
> [ ... ]
> > > 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.
>
> <orcmid>
> Well, the problem is we can't just tell everyone they have to use Unix
> Newline codes and not use CR-LF. First, it makes no sense if they are
> operating on Windows, and it only matters for code that is exchanged
> via the repo. (It matters for patches too, but my brain just exploded.)
>
> That means we need to explain how to ensure that only Unix Newline codes
> end up in the repository, which is where it matters.
>
> I did find out where in GitHub there is information about this. Here it
> is again:
>
> The line-ending does have controls in SVN and Git configurations.
> So long as a file is known to be text, there are controls in place.
> Here is GitHub on the subject,
> <https://help.github.com/articles/dealing-with-line-endings/>.
>
> Note that it is very important to be certain that Git knows what files
> *not* to make these adjustments on, since it will damage binaries too
> when they are not excluded from treatment as text. I don't know how
> much this impacts PGP-signed material.
>
> I suggest the .gitattributes approach be set up in the Corinthia
> repository with text=auto and the indicated examples. After that is
> done, those of us using Windows may need to re-clone the repository
> to have everything in sync.
>
> PS: I have no idea how line ends show up in the batch scripts I
> put on the repository. They work fine for me, of course.
> </orcmid>
>
> [ ... ]
>
>
--
Sent from My iPad, sorry for any misspellings.
RE: Coding Standards page
Posted by "Dennis E. Hamilton" <or...@apache.org>.
I have added an appropriate (I hope) .gitattributes file to the Corinthia repository.
For SVN, it is necessary to make local changes to adjust line-endings cross-platform. The relevant ASF file for this is at <http://www.apache.org/dev/svn-eol-style.txt>.
It turns out I have a custom one of these *and* it is in effect. The problem was I had replaced the rules for *.html and *.htm with ones that specified the MIME type and removed the svn:eol-style attribute, thinking it didn't matter. My bad. I did that years ago! (June 2011) It does matter for DIFF and for what others think the "right" line ending is.
I have fixed that in my local SVN settings.
PS: I have the SVN definitions for the ODF documents, and I need to update them for the Microsoft Office documents. I assume that having these binaries is all right in collections of test documents, so long as they are not in the part of our repositories that represent released source code.
- Dennis
-----Original Message-----
From: Dennis E. Hamilton [mailto:dennis.hamilton@acm.org]
Sent: Tuesday, January 6, 2015 12:48
To: dev@corinthia.incubator.apache.org
Subject: RE: Coding Standards page
-- replying below to --
From: jan i [mailto:jani@apache.org]
Sent: Tuesday, January 6, 2015 11:38
To: dev@corinthia.incubator.apache.org
Subject: Re: Coding Standards page
On Tuesday, January 6, 2015, Peter Kelly <pm...@apache.org> wrote:
> > On 7 Jan 2015, at 1:26 am, Dennis E. Hamilton <dennis.hamilton@acm.org
> <javascript:;>> wrote:
[ ... ]
> > 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.
<orcmid>
Well, the problem is we can't just tell everyone they have to use Unix
Newline codes and not use CR-LF. First, it makes no sense if they are
operating on Windows, and it only matters for code that is exchanged
via the repo. (It matters for patches too, but my brain just exploded.)
That means we need to explain how to ensure that only Unix Newline codes
end up in the repository, which is where it matters.
I did find out where in GitHub there is information about this. Here it
is again:
The line-ending does have controls in SVN and Git configurations.
So long as a file is known to be text, there are controls in place.
Here is GitHub on the subject,
<https://help.github.com/articles/dealing-with-line-endings/>.
Note that it is very important to be certain that Git knows what files
*not* to make these adjustments on, since it will damage binaries too
when they are not excluded from treatment as text. I don't know how
much this impacts PGP-signed material.
I suggest the .gitattributes approach be set up in the Corinthia
repository with text=auto and the indicated examples. After that is
done, those of us using Windows may need to re-clone the repository
to have everything in sync.
PS: I have no idea how line ends show up in the batch scripts I
put on the repository. They work fine for me, of course.
</orcmid>
[ ... ]
RE: Coding Standards page
Posted by "Dennis E. Hamilton" <de...@acm.org>.
-- replying below to --
From: jan i [mailto:jani@apache.org]
Sent: Tuesday, January 6, 2015 11:38
To: dev@corinthia.incubator.apache.org
Subject: Re: Coding Standards page
On Tuesday, January 6, 2015, Peter Kelly <pm...@apache.org> wrote:
> > On 7 Jan 2015, at 1:26 am, Dennis E. Hamilton <dennis.hamilton@acm.org
> <javascript:;>> wrote:
[ ... ]
> > 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.
<orcmid>
Well, the problem is we can't just tell everyone they have to use Unix
Newline codes and not use CR-LF. First, it makes no sense if they are
operating on Windows, and it only matters for code that is exchanged
via the repo. (It matters for patches too, but my brain just exploded.)
That means we need to explain how to ensure that only Unix Newline codes
end up in the repository, which is where it matters.
I did find out where in GitHub there is information about this. Here it
is again:
The line-ending does have controls in SVN and Git configurations.
So long as a file is known to be text, there are controls in place.
Here is GitHub on the subject,
<https://help.github.com/articles/dealing-with-line-endings/>.
Note that it is very important to be certain that Git knows what files
*not* to make these adjustments on, since it will damage binaries too
when they are not excluded from treatment as text. I don't know how
much this impacts PGP-signed material.
I suggest the .gitattributes approach be set up in the Corinthia
repository with text=auto and the indicated examples. After that is
done, those of us using Windows may need to re-clone the repository
to have everything in sync.
PS: I have no idea how line ends show up in the batch scripts I
put on the repository. They work fine for me, of course.
</orcmid>
[ ... ]
Re: Coding Standards page
Posted by jan i <ja...@apache.org>.
On Tuesday, January 6, 2015, Peter Kelly <pm...@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.
Re: Coding Standards page
Posted by Peter Kelly <pm...@apache.org>.
> On 7 Jan 2015, at 1:26 am, Dennis E. Hamilton <de...@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)