All definitions should reside in source files.

[simonlynen]

What about inlining?

If inlining is desired, the respective function definition should be moved to a separate implementation header which is included at the end of the header.

[stephanemagnenat]

And templates?

[stephanemagnenat]

And what about autodoc? In general, I put all autodoc in source file to keep headers clean, excepted for templates and inline members.

[furgalep]

I agree that all implementations should be in separate files. Can we have inlines/template implementations in implementation/MyClass.hpp. As Simon said, this should be included at the end of the class.

[stephanemagnenat]

Just a general comment: In my own experience, I realized that simplicity of access to the code is also important, and not only theoretical clarity should be considered. For instance, with small classes it makes sense to group them in a single pair of .h/.cpp files. I know that some people are using fairly sophisticated IDE, but some other people are using simpler editors. The file structure should not be uselessly complicated. I think that the common sense should have more importance than strict guidelines.

[furgalep]

Stephane, do you mean that, is some cases, we should relax this policy and allow inline functions defined in the header? I think that could fit under the rule:

1. Any violation to the guide is allowed if it enhances readability.

The main goal of the recommendation is to improve readability and thereby the understanding and the maintainability and general quality of the code. It is impossible to cover all the specific cases in a general guide and the programmer should be flexible.

[HannesSommer]

• I vote for the possibility of grouping classes in one file in some situations, as Stephane suggested. (I especially think of trait classes or some hidden, default implementations for public interfaces).
• I also would like to suggest allowing very short inline functions (e.g. single statement, typically getters, setters, or constructors with simple initialization lists only) to be defined directly in their declaring class. Because for me the additional effort and risk introduced by the duplication (as by any duplication) of the extended signature, class name and template parameters (the classe's and eventually the method's (e.g. templated constructors)) weights a lot more then the pure ideal of separation - at least for small methods. Additionally for me the readability is even increased with small methods in the class: then I can instantly see: this is a trivial function doing nothing special - and I do not have to switch the file to find out that important peace of information. In the java world they live very well without even having the possibility of postponed definition. I guess that was one reason for them to define javadoc together with the language. Header files are in the end not documentation but in fact sources files. And source files may get dirty: For example some internal parts have to be put before the class (e.g. traits, other internal stuff necessary in the definitions - look into Eigen header files as an example). If one puts those again in a separate file you have to maintain together with the template/inline implementation necessarily two (!) additional files (or a #define - guard nightmare) for one class.
• We could consequentially (considering my last point) recommend / require support for a good c++ documentation generators to reduce the requirement load on the code style?

[stephanemagnenat]

I fully agree with Hannes!

I also agree with you Paul that this could fit under the "rule violation because of common sense" rule. But I believe that as the guide we are writing is also a help for people not at ease with C++, it should help them to get a feeling how to code reasonably. One problem with beginners, just after very ugly code, is over-complicated code. I think that in the guide we should also give a feeling that coding has an artistic part, with an important common-sense component. Large classes holding significant part of the program logic should of course lie in their own files, but collections of support classes, especially when they are inter-dependant and templatized, are better grouped in a single or few files, in my opinion.

[simonlynen]

@HannesSommer Hannes could you integrate your comment to the style-guide? Thanks!