You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@mynewt.apache.org by Christopher Collins <cc...@apache.org> on 2016/11/04 23:34:27 UTC
Angled-brackets vs. quotes in #include directives
Hello all,
We've been a bit inconsistent with our use of angled-brackets vs. quotes
in #include directives. There is a simple rule for this one: use
quotes for user headers; angled-brackets for headers supplied by the
implementation. "Implementation" is a technical term meaning the
combination of compiler, standard library, linker, assembler, etc.
In other words,
GOOD:
#include <stdio.h>
#include <assert.h>
#include "os/os.h"
BAD:
#include <stdio.h>
#include <assert.h>
#include <os/os.h>
BAD:
#include "stdio.h"
#include "assert.h"
#include "os/os.h"
Thanks,
Chris
Re: Angled-brackets vs. quotes in #include directives
Posted by Adam <ad...@gmail.com>.
If you're tightening up coding standards, I'd suggest running "go fmt"
before pushing in the newt repo.
Adam
On Fri, Nov 4, 2016 at 6:01 PM, Sterling Hughes <st...@apache.org> wrote:
>
>
> On 4 Nov 2016, at 16:34, Christopher Collins wrote:
>
> > Hello all,
> >
> > We've been a bit inconsistent with our use of angled-brackets vs. quotes
> > in #include directives. There is a simple rule for this one: use
> > quotes for user headers; angled-brackets for headers supplied by the
> > implementation. "Implementation" is a technical term meaning the
> > combination of compiler, standard library, linker, assembler, etc.
> >
> > In other words,
> >
> > GOOD:
> >
> > #include <stdio.h>
> > #include <assert.h>
> > #include "os/os.h"
> >
> > BAD:
> >
> > #include <stdio.h>
> > #include <assert.h>
> > #include <os/os.h>
> >
> > BAD:
> >
> > #include "stdio.h"
> > #include "assert.h"
> > #include "os/os.h"
> >
>
> +1
>
> Let’s get this added to the CODING_STANDARDS
>
> :)
>
> sterling
>
Re: Angled-brackets vs. quotes in #include directives
Posted by Sterling Hughes <st...@apache.org>.
Hi,
On 7 Nov 2016, at 19:04, Christopher Collins wrote:
> On Mon, Nov 07, 2016 at 09:45:48AM -0800, marko kiiskila wrote:
>>> On Nov 7, 2016, at 8:43 AM, Christopher Collins
>>> <cc...@apache.org> wrote:
>>> Is there a particular reason that you would prefer this? By my
>>> reading
>>> of the standard, using angled-brackets for this purpose contradicts
>>> their specified purpose, at least in spirit.
>>
>> Familiarity of practice, I guess.
>>
>> http://lxr.free-electrons.com/source/kernel/sched/core.c
>> <http://lxr.free-electrons.com/source/kernel/sched/core.c>
>> https://www.freebsd.org/cgi/man.cgi?query=style&sektion=9
>> <https://www.freebsd.org/cgi/man.cgi?query=style&sektion=9>
>>
>> However, I\u2019m not too tied to this, if you have a very strong
>> preference.
>
> I don't think the Linux or FreeBSD kernels are a good example of
> portable code! Honestly, I don't think there is any practical benefit
> in doing it my way. My only interest in this issue is that I wince
> whenever I see user headers being included with angle-brackets. If
> there is any practical reason to do something different, then we
> should
> do it - that's why I asked if there was a particular reason for the
> preference.
>
> I think someone will update the coding standards file with some rule,
> and everyone will be happy :).
>
I\u2019m fine with either. I\u2019ve also always adhered to what Marko
described (separate popular OS project had this as CODING STANDARD), but
I\u2019m fine changing my habits.
+1 for keeping it consistent: either way.
Sterling
Re: Angled-brackets vs. quotes in #include directives
Posted by Christopher Collins <cc...@apache.org>.
On Mon, Nov 07, 2016 at 09:45:48AM -0800, marko kiiskila wrote:
> > On Nov 7, 2016, at 8:43 AM, Christopher Collins <cc...@apache.org> wrote:
> > Is there a particular reason that you would prefer this? By my reading
> > of the standard, using angled-brackets for this purpose contradicts
> > their specified purpose, at least in spirit.
>
> Familiarity of practice, I guess.
>
> http://lxr.free-electrons.com/source/kernel/sched/core.c <http://lxr.free-electrons.com/source/kernel/sched/core.c>
> https://www.freebsd.org/cgi/man.cgi?query=style&sektion=9 <https://www.freebsd.org/cgi/man.cgi?query=style&sektion=9>
>
> However, I\u2019m not too tied to this, if you have a very strong preference.
I don't think the Linux or FreeBSD kernels are a good example of
portable code! Honestly, I don't think there is any practical benefit
in doing it my way. My only interest in this issue is that I wince
whenever I see user headers being included with angle-brackets. If
there is any practical reason to do something different, then we should
do it - that's why I asked if there was a particular reason for the
preference.
I think someone will update the coding standards file with some rule,
and everyone will be happy :).
Chris
Re: Angled-brackets vs. quotes in #include directives
Posted by marko kiiskila <ma...@runtime.io>.
> On Nov 7, 2016, at 8:43 AM, Christopher Collins <cc...@apache.org> wrote:
>
> On Mon, Nov 07, 2016 at 08:08:14AM -0800, marko kiiskila wrote:
>> Good idea to write this down.
>>
>> I’d also like to include header files from other packages to be in the
>> group included with angle brackets.
>> Then “header.h” means local and <header.h> is for non-local.
>
> Is there a particular reason that you would prefer this? By my reading
> of the standard, using angled-brackets for this purpose contradicts
> their specified purpose, at least in spirit.
Familiarity of practice, I guess.
http://lxr.free-electrons.com/source/kernel/sched/core.c <http://lxr.free-electrons.com/source/kernel/sched/core.c>
https://www.freebsd.org/cgi/man.cgi?query=style&sektion=9 <https://www.freebsd.org/cgi/man.cgi?query=style&sektion=9>
However, I’m not too tied to this, if you have a very strong preference.
> This is from n1570 (free draft of the 2011 standard, available at
> http://www.iso-9899.info/n1570.html):
>
> (6.10.2)
> 2 A preprocessing directive of the form
> # include <h-char-sequence> new-line
> searches a sequence of implementation-defined places for a header
> identified uniquely by the specified sequence between the < and >
> delimiters, and causes the replacement of that directive by the
> entire contents of the header. How the places are specified or the
> header identified is implementation-defined.
>
> 3 A preprocessing directive of the form
> # include "q-char-sequence" new-line
> causes the replacement of that directive by the entire contents of
> the source file identified by the specified sequence between the "
> delimiters. The named source file is searched for in an
> implementation-defined manner. If this search is not supported, or
> if the search fails, the directive is reprocessed as if it read
> # include <h-char-sequence> new-line
> with the identical contained sequence (including > characters, if
> any) from the original directive.
>
> The relevant difference among these paragraphs is "header" vs. "source
> file." When you use angle-brackets, the compiler includes
> implementation-specific source. This is usually a plain C file, but it
> could also be some sort of precompiled header or dynamically generated
> magic. With double quotes, a file always gets included. Since we don't
> control the implementation (and in fact expect Mynewt to build with
> several different implementations), it would seem that we should only
> use angled-brackets for implementation-supplied files.
>
> Chris
Re: Angled-brackets vs. quotes in #include directives
Posted by Christopher Collins <cc...@apache.org>.
On Mon, Nov 07, 2016 at 08:08:14AM -0800, marko kiiskila wrote:
> Good idea to write this down.
>
> I\u2019d also like to include header files from other packages to be in the
> group included with angle brackets.
> Then \u201cheader.h\u201d means local and <header.h> is for non-local.
Is there a particular reason that you would prefer this? By my reading
of the standard, using angled-brackets for this purpose contradicts
their specified purpose, at least in spirit.
This is from n1570 (free draft of the 2011 standard, available at
http://www.iso-9899.info/n1570.html):
(6.10.2)
2 A preprocessing directive of the form
# include <h-char-sequence> new-line
searches a sequence of implementation-defined places for a header
identified uniquely by the specified sequence between the < and >
delimiters, and causes the replacement of that directive by the
entire contents of the header. How the places are specified or the
header identified is implementation-defined.
3 A preprocessing directive of the form
# include "q-char-sequence" new-line
causes the replacement of that directive by the entire contents of
the source file identified by the specified sequence between the "
delimiters. The named source file is searched for in an
implementation-defined manner. If this search is not supported, or
if the search fails, the directive is reprocessed as if it read
# include <h-char-sequence> new-line
with the identical contained sequence (including > characters, if
any) from the original directive.
The relevant difference among these paragraphs is "header" vs. "source
file." When you use angle-brackets, the compiler includes
implementation-specific source. This is usually a plain C file, but it
could also be some sort of precompiled header or dynamically generated
magic. With double quotes, a file always gets included. Since we don't
control the implementation (and in fact expect Mynewt to build with
several different implementations), it would seem that we should only
use angled-brackets for implementation-supplied files.
Chris
Re: Angled-brackets vs. quotes in #include directives
Posted by marko kiiskila <ma...@runtime.io>.
Good idea to write this down.
I’d also like to include header files from other packages to be in the
group included with angle brackets.
Then “header.h” means local and <header.h> is for non-local.
> On Nov 4, 2016, at 6:01 PM, Sterling Hughes <st...@apache.org> wrote:
>
>
>
> On 4 Nov 2016, at 16:34, Christopher Collins wrote:
>
>> Hello all,
>>
>> We've been a bit inconsistent with our use of angled-brackets vs. quotes
>> in #include directives. There is a simple rule for this one: use
>> quotes for user headers; angled-brackets for headers supplied by the
>> implementation. "Implementation" is a technical term meaning the
>> combination of compiler, standard library, linker, assembler, etc.
>>
>> In other words,
>>
>> GOOD:
>>
>> #include <stdio.h>
>> #include <assert.h>
>> #include "os/os.h"
>>
>> BAD:
>>
>> #include <stdio.h>
>> #include <assert.h>
>> #include <os/os.h>
>>
>> BAD:
>>
>> #include "stdio.h"
>> #include "assert.h"
>> #include "os/os.h"
>>
>
> +1
>
> Let’s get this added to the CODING_STANDARDS
>
> :)
>
> sterling
Re: Angled-brackets vs. quotes in #include directives
Posted by Sterling Hughes <st...@apache.org>.
On 4 Nov 2016, at 16:34, Christopher Collins wrote:
> Hello all,
>
> We've been a bit inconsistent with our use of angled-brackets vs. quotes
> in #include directives. There is a simple rule for this one: use
> quotes for user headers; angled-brackets for headers supplied by the
> implementation. "Implementation" is a technical term meaning the
> combination of compiler, standard library, linker, assembler, etc.
>
> In other words,
>
> GOOD:
>
> #include <stdio.h>
> #include <assert.h>
> #include "os/os.h"
>
> BAD:
>
> #include <stdio.h>
> #include <assert.h>
> #include <os/os.h>
>
> BAD:
>
> #include "stdio.h"
> #include "assert.h"
> #include "os/os.h"
>
+1
Let\u2019s get this added to the CODING_STANDARDS
:)
sterling