[wwwdocs] Update coding conventions for C++

[Lawrence Crowl]

On 6/25/12, Benjamin Kosnik <bkoz@redhat.com> wrote:
> The only remaining issue for me is the fuzzyness/handwaving
> around inlining.  I think the only way to really enforce "what
> can be inlined" is not to have people use their best judgement,
> or what they think is a small function, or what they intend
> for the compiler to inline, but to have -Winline mandatory.
> And thus flag things that are written as inlined, but cannot then
> be inlined by the compiler.
>
> This area seems historically fraught, in terms of expectations.
> I'm not trying to poke at the hornets nest here.

I see two problems with trying to use -Winline.

First, the implication is that if the compiler does not complain with
-Winline, then the inlining is fine.  The compiler only warns when
it cannot inline, not when that inlining is counter productive.  That
is, we want inlining when we win in either space or time, an -Winline
does not tell us that.  So, in a sense, the warning is too weak.

Second, together -Winline and -Werror lead to a tempermental build.
The documentation for -Winline says:

  Warn if a function can not be inlined and it was declared as
  inline. Even with this option, the compiler will not warn about
  failures to inline functions declared in system headers.

  The compiler uses a variety of heuristics to determine whether
  or not to inline a function. For example, the compiler takes
  into account the size of the function being inlined and the
  amount of inlining that has already been done in the current
  function. Therefore, seemingly insignificant changes in the
  source program can cause the warnings produced by -Winline to
  appear or disappear.

IIUC, a small change to a function in a header file could cause
a hundred other functions to suddenly start emitting the warning,
causing the edit of files that would not normally be considered part
of the patch.  In the worst case, these functions would shift from
header to source file, causing even more source churn.  Even more
disconcerting, the warning might not show up until later in the boot.

If everyone keeps their inlines small and clean, maybe the second
problem will not be so much of a problem.  My concern is that writing
it into the coding conventions shifts the practical consequences
to places that are hard to anticipate and hard to deal with.
For instance, suppose I inline foo() to meet performance goals,
but in doing so bar() becomes to large to inline.  Was bar() too
performance critical to make non-inline?  If so, how do I best
refactor bar()?  Will I need another maintainer to review the code
because of that refactoring?

With that concern stated, I will write into the conventions whatever
concensus arises.

Of course, I have no objection to an occasional inline cleanup.
That is, build with -Werror and adjusting inlines that have,
through the course of time, become larger than is useful.

-- 
Lawrence Crowl