questions on the LLVM coding standards

Hi Chris,

While reading the LLVM coding standards
(http://llvm.org/docs/CodingStandards.html), I have some questions:

1. It says "you shouldn't assume much about the host compiler,
including its support for "high tech" features like partial
specialization of templates." Is this still the case? I'm a bit
surprised that we need to worry about compilers that don't understand
partial specialization.

2. It advises to #include as little as possible. In particular,
"Don't do it unless you have to, especially in header files." And
later it says "you can include them either directly or indirectly
(through another header file)." I'm worried that this may lead
dependencies on other headers' implementation details. For example,
if foo.cpp needs b.h, I would think it should #include b.h itself,
instead of relying on some other .h file that happens to include b.h
(unless it's the other .h file's intention to "re-export" b.h). What
are your thoughts on this?

3. It says "For example, all of the code in the LLVM project
implements code that lives in the 'llvm' namespace. As such, it is ok,
and actually clearer, for the .cpp files to have a 'using namespace
llvm' directive at their top, after the #includes. The general form of
this rule is that any .cpp file that implements code in any namespace
may use that namespace (and its parents'), but should not use any
others."

I don't understand why this is necessary. Since the .cpp is
implementing code in the llvm namespace, why not enclosing its entire
body in namespace llvm? In that case, there's no need for 'using
namespace llvm'.

Thanks,

While reading the LLVM coding standards
(http://llvm.org/docs/CodingStandards.html), I have some questions:

1. It says "you shouldn't assume much about the host compiler,
including its support for "high tech" features like partial
specialization of templates." Is this still the case? I'm a bit
surprised that we need to worry about compilers that don't understand
partial specialization.

Good point, I updated this section. Partial specialization should still be used sparingly, but just because it can lead to confusing code, not to non-portable code.

2. It advises to #include as little as possible. In particular,
"Don't do it unless you have to, especially in header files." And
later it says "you can include them either directly or indirectly
(through another header file)." I'm worried that this may lead
dependencies on other headers' implementation details.

Yes, this is a possible issue, but since LLVM is a relatively self-contained ecosystem, any issues that arise from this can be addressed by fixing the clients of the headers.

This is in direct contrast to the apparent situation at Google, where they prefer "include what you use". That approach is taken because it is difficult or expensive to find and update all the clients.

3. It says "For example, all of the code in the LLVM project
implements code that lives in the 'llvm' namespace. As such, it is ok,
and actually clearer, for the .cpp files to have a 'using namespace
llvm' directive at their top, after the #includes. The general form of
this rule is that any .cpp file that implements code in any namespace
may use that namespace (and its parents'), but should not use any
others."

I don't understand why this is necessary. Since the .cpp is
implementing code in the llvm namespace, why not enclosing its entire
body in namespace llvm? In that case, there's no need for 'using
namespace llvm'.

It is not "necessary", in that it doesn't affect the semantics of the program. It is better that putting the entire body of the .cpp file in "namespace llvm {" because it reduces nesting and interoperates better with IDEs that like to indent according to braces.

-Chris

While reading the LLVM coding standards
(http://llvm.org/docs/CodingStandards.html), I have some questions:

[ snip ]

2. It advises to #include as little as possible. In particular,
"Don't do it unless you have to, especially in header files." And
later it says "you can include them either directly or indirectly
(through another header file)." I'm worried that this may lead
dependencies on other headers' implementation details.

Yes, this is a possible issue, but since LLVM is a relatively self-contained ecosystem, any issues that arise from this can be addressed by fixing the clients of the headers.

This is in direct contrast to the apparent situation at Google, where they prefer "include what you use". That approach is taken because it is difficult or expensive to find and update all the clients.

I've been playing with libclang, and trying to adapt c-index-test to make an include file tester.

The idea would be twofold:
  1) Generate a "tree" of includes, so you can see the path where file gets included from. The existing code in c-index-test gives a different view, showing where each file is included from.
  2) Some way of detecting "unused" included files, so that they can be removed.

I'm waiting anixously for the video of Craig Silverstein's talk from the developer meeting to see what he's already done.

Is this something that either
  a) has been done already
or b) other people would be interested in?

-- Marshall

Thanks for clarifying, Chris!

Marshall Clow wrote:

While reading the LLVM coding standards
(http://llvm.org/docs/CodingStandards.html), I have some questions:

[ snip ]

2. It advises to #include as little as possible. In particular,
"Don't do it unless you have to, especially in header files." And
later it says "you can include them either directly or indirectly
(through another header file)." I'm worried that this may lead
dependencies on other headers' implementation details.

Yes, this is a possible issue, but since LLVM is a relatively
self-contained ecosystem, any issues that arise from this can be
addressed by fixing the clients of the headers.

This is in direct contrast to the apparent situation at Google, where
they prefer "include what you use". That approach is taken because it is
difficult or expensive to find and update all the clients.

I've been playing with libclang, and trying to adapt c-index-test to make
an include file tester.

The idea would be twofold:
1) Generate a "tree" of includes, so you can see the path where file gets
included from. The existing code in c-index-test gives a different view,
showing where each file is included from. 2) Some way of detecting
"unused" included files, so that they can be removed.

I'm waiting anixously for the video of Craig Silverstein's talk from the
developer meeting to see what he's already done.

Is this something that either
a) has been done already
or b) other people would be interested in?

Yes, I am. I'm working on a C++ project analyzer [1] and also like to add
things like this at some point. Another thing I wanted to implement using
this information extracted by clang and related to this is,
buildcost/buildimpact analysis as described in this paper:

http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.164.587&rep=rep1&type=pdf

Related work I did, based on the KDevelop IDE/C++ parsing framework can be
found here [2] and here [3], but I found that framework in the end not clean
enough, limited in its capabilities and not such a wide acceptance as clang.

Cheers,

Bertjan

[1] http://www.gitorious.org/cpp-dependency-analyzer/
[2] http://www.gitorious.org/kdevcpptools/kdevcpptools
[3] http://bertjan.broeksemaatjes.nl/files/ClassicThesis.pdf

It is not "necessary", in that it doesn't affect the semantics of the program. It is better that putting the entire body of the .cpp file in "namespace llvm {" because it reduces nesting and interoperates better with IDEs that like to indent according to braces.

I see. It would be nice to add this rationale to the page. Although
I can also understand it if you don't want to bloat it...

Sure, done in r119544. I don't know if it is more or less confusing, but there ya go :slight_smile:

Have you seen my patch that fixes some typos and formatting nits in
the coding standards? It should be in your inbox waiting for your
review. Thanks,

Yep, applied, thanks!

-Chris

Thanks for doing both, Chris!