Patchwork [wwwdocs] Update coding conventions for C++

login
register
mail settings
Submitter Lawrence Crowl
Date June 25, 2012, 10:26 p.m.
Message ID <CAGqM8fa2pUWeJm-1rwMLntMc9EAGAp57ys0KEcCcWQP2856rhA@mail.gmail.com>
Download mbox | patch
Permalink /patch/167243/
State New
Headers show

Comments

Lawrence Crowl - June 25, 2012, 10:26 p.m.
On 6/25/12, Lawrence Crowl <crowl@google.com> wrote:
> On 6/25/12, Joseph S. Myers <joseph@codesourcery.com> wrote:
>> On Mon, 25 Jun 2012, Diego Novillo wrote:
>> > [ Added doc maintainers in CC ]
>> >
>> > While I'm not particularly interested in the details of the
>> > coding conventions, I am interested in getting them in getting
>> > them installed before we merge cxx-conversion to trunk.
>> >
>> > Joseph, Gerald, do we have a process for accepting changes to
>> > coding conventions?
>>
>> I suggest sending smaller (so easier to review) patches that are
>> concrete and avoid speculation about possible future changes.
>
> The speculative parts come from the wiki.  Unless I had specific
> reason to remove them, I left them.
>
>> > > +&nbsp;&nbsp;&nbsp;&nbsp;<a href="#C_Options">Compiler Options</a><br
>> > > />
>>
>> I don't like this repeated &nbsp; presentational markup; use
>> appropriate logical markup instead.
>
> Done.
>
>> > > +<p>
>> > > +We will periodically pick a stable version of GCC,
>> > > +and require that that version of GCC be able to build
>> > > +all versions of GCC up to and including the next stable version.
>> > > +E.g., we may decide that all newer versions of GCC
>> > > +should be buildable with GCC 4.3.5.
>>
>> The current version required is more important than speculation
>> about future changes.  E.g., say that code must build with GCC
>> 4.1 and later.
>
> After some off-line discussion with Diego, I have removed some of
> text in this area.  It now focuses on being portable, rather than
> on arbitrary version numbers.
>
>> > > +<h4><a name="Assertions">Assertions</a></h4>
>> > > +
>> > > +<p>Code should use <code>gcc_assert(EXPR)</code> to check
>> > > invariants.
>> > > +Use <code>gcc_unreachable()</code> to mark places that should never
>> > > be
>> > > +reachable (such as an unreachable <code>default</code> case of a
>> > > +switch).  Do not use <code>gcc_assert(0)</code> for such purposes,
>> > > as
>> > > +<code>gcc_unreachable</code> gives the compiler more information.
>> > > The
>> > > +assertions are enabled unless explicitly configured off with
>> > > +<code>--enable-checking=none</code>.  Do not use <code>abort</code>.
>> > > +User input should never be validated by either
>> > > <code>gcc_assert</code>
>> > > +or <code>gcc_unreachable</code>.  If the checks are expensive or the
>> > > +compiler can reasonably carry on after the error, they may be
>> > > +conditioned on <code>--enable-checking</code>.</p>
>>
>> I don't think any of this is new - perhaps you could separate
>> rearrangement from the actual changes and C++ conventions?
>
> The section titles are new, but the text itself is not.  There did
> not seem to be a reasonable way to separate the rearrangment from
> the new context in which it was placed.
>
>> > > +<h4><a name="Calls">Function Calls</a></h4>
>> > > +
>> > > +<p>
>> > > +All current GCC code uses a space between the function name
>> > > +and the left parenthesis in a function call.
>> > > +Essentially all C++ code omits that space,
>> > > +which is more consistent with C++ syntax.
>> > > +For the present we will retain the space.
>> > > +It is possible that in the future we will switch the code with a flag
>> > > day.
>> > > +</p>
>>
>> Avoid speculation.  Avoid duplicating the GNU Coding Standards.
>> Formatting can be assumed to follow the GNU Coding Standards
>> except where they are meaningless for C++ or something explicitly
>> overrides them.
>
> That paragraph came from the wiki.  I have removed it.
>
>> > > +<p>
>> > > +Think carefully about the size and performance impact
>> > > +of virtual functions and virtual bases
>> > > +before using them.
>> > > +</p>
>>
>> Explain in more detail what the size and performance impact is
>> for people not familiar with the details of how C++ features
>> are implemented.
>
> I have added a bit more in the rationale, reached through the link
> at the end of that section.
>
>> > > +<p>
>> > > +Indent protection labels by one space.
>> > > +</p>
>> > > +
>> > > +<p>
>> > > +Indent class members by two spaces.
>>
>> Do all the listed indentation rules correspond to what a <TAB>
>> will do by default when editing C++ code in GNU Emacs?  If not,
>> we have conflicting notions of GNU C++ indentation conventions.
>
> I have no idea.  I don't use emacs.  The two-space rule for members
> comes from the wiki.  The one-space rule for protection labels is
> common practice.  If folks want something else, changes are fine
> with me.
>
> I have also made a few other edits requested offline by Benjamin
> Kosnik.
>
> --
> Lawrence Crowl

Sorry, I forgot to add the patch.  Note that I have removed some
html headers that cause gcc mail grief.
Benjamin Kosnik - June 25, 2012, 11:37 p.m.
Hey Lawrence, thanks for this work and for keeping the public
up-to-date with this gcc-patches posting.

This looks pretty good to me. 

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.

-benjamin
Lawrence Crowl - June 26, 2012, 12:08 a.m.
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.
Alexandre Oliva - June 26, 2012, 4:54 a.m.
On Jun 25, 2012, Lawrence Crowl <crowl@google.com> wrote:

> +These conventions will change over time,
> +but changing them requires that a convincing rationale.

s/that//

> +Complex heirarchies are to be avoided.

s/heir/hier/
Martin Jambor - June 26, 2012, 12:45 p.m.
Hi,

On Mon, Jun 25, 2012 at 03:26:01PM -0700, Lawrence Crowl wrote:
...
> > I have no idea.  I don't use emacs.  The two-space rule for members
> > comes from the wiki.  The one-space rule for protection labels is
> > common practice.  If folks want something else, changes are fine
> > with me.

I'll also need an emacs C++ indentation style that conforms to this in
order to really be able to produce complying code myself.  So if
anybody else will be working on that, I'm interested (to use it and
perhaps help crafting it) and I guess a number of other people on this
list are too...

Furthermore, even though this mainly reminds me how little I actually
know about C++, I have a few general tiny comments:

> -<h2>Miscellaneous Conventions</h2>
> -
> -<p>Code should use <code>gcc_assert(EXPR)</code> to check invariants.
> -Use <code>gcc_unreachable()</code> to mark places that should never be
> -reachable (such as an unreachable <code>default</code> case of a
> -switch).  Do not use <code>gcc_assert(0)</code> for such purposes, as
> -<code>gcc_unreachable</code> gives the compiler more information.  The
> -assertions are enabled unless explicitly configured off with
> -<code>--enable-checking=none</code>.  Do not use <code>abort</code>.
> -User input should never be validated by either <code>gcc_assert</code>
> -or <code>gcc_unreachable</code>.  If the checks are expensive or the
> -compiler can reasonably carry on after the error, they may be
> -conditioned on <code>--enable-checking</code>.</p>

It seems we should mention gcc_checking_assert here then.

...

> +<p>
> +Single inheritance is permitted.
> +Use public inheritance to describe interface inheritance,
> +i.e. 'is-a' relationships.
> +Use private and protected inheritance
> +to describe implementation inheritance.
> +Implementation inheritance can be expediant,

s/expediant/expedient/

> +but think twice before using it in code
> +intended to last a long time.

I think all committed code should be expected to have long-lasting
quality.  I would not encourage people to think otherwise and would
drop the "long time" reference here.  If anybody ever commits
something ugly to bridge a short time period, it should only be done
under the "maintainers grant exceptions" rule anyway.

...

> +</p>> +<p>
> +For long-term code, at least for now,
> +we will continue to use <code>printf</code> style I/O
> +rather than <code>&lt;iostream&gt;</code> style I/O.
> +For quick debugging code,
> +<code>&lt;iostream&gt;</code> is permitted.
> +</p>

Similarly here, no quick and dirty debugging output should ever be
committed, we should not 

> +<h4><a name="stdlib">The Standard Library</a></h4>
> +
> +<p>
> +At present, C++ provides no great advantage for i18n.
> +GCC does type checking for <code>printf</code> arguments,
> +so the type insecurity of <code>printf</code> is moot,
> +but the clarity in layout persists.
> +For quick debugging output, &lt;iostream&gt; requires less work.
> +</p>

The same applies here.

Thanks,

Martin


> +
> +<h3>Formatting Conventions</h3>
> +
> +<h4><a href="names">Names</a></h4>
> +
> +<p>
> +Naming data members with a trailing underscore
> +highlights the extra overhead of access to fields over local variables.
> +Think of the trailing underscore
> +like you would Pascal's postfix <code>^</code> dereference operator.
> +</p>
> +
> +<p>
> +When using the above convention,
> +the constructor parameter names
> +and getter member function names
> +can use the more concise non-underscore form.
> +</p>
> +
> +</body>
> +</html>
> 
> -- 
> Lawrence Crowl
Jason Merrill - June 26, 2012, 3:19 p.m.
On 06/25/2012 06:26 PM, Lawrence Crowl wrote:
> +or<code>gcc_unreachable</code>.  If the checks are expensive or the
> +compiler can reasonably carry on after the error, they may be
> +conditioned on<code>--enable-checking</code>.</p>

by using <code>gcc_checking_assert</code>

[Rationale]
> +FIXME: Discussion of deleting inappropraite special members.

Is this FIXME still needed?  The text following it seems to cover the 
issue well enough.

> +However, by default, RTTI is not permitted
> +and the compiler must build cleanly with <code>-fno-rtti</code>.

This seems like an unnecessary restriction to me.

> +Disabling RTTI will save space in the compiler.

This is a fine reason to disable RTTI if it isn't used, but doesn't seem 
like a strong reason to prohibit using it.  The information is only 
emitted for classes with virtual functions, isn't very large, is 
typically emitted in only one object file, and since it lives in .rodata 
it can be shared between multiple compiler processes.

> +Checking the type of a class at runtime usually indicates a design problem.

The tree_contains_struct machinery recently added to GCC maps directly 
onto dynamic_cast;

if (CODE_CONTAINS_STRUCT(TREE_CODE(t),TS_DECL_WRTL))
   /* do something with t->decl_with_rtl */

translates roughly to to

if (decl_with_rtl *p = dynamic_cast <decl_with_rtl *>(t))
   /* do something with p */

When new interfaces are added partway down an inheritance tree, 
dynamic_cast is the right way to access them.  This isn't checking what 
the type is, it's checking whether the object supports a particular method.

The fact that we've gone to the trouble to implement this functionality 
in C suggests to me that using it isn't always indicative of a design 
problem.  :)

> +If you need to know the type of a class for some other reason,
> +use an enum or a virtual member function
> +that coverts a pointer to the more derived class.
> +For example,
> +</p>
> +
> +<blockquote><pre><code>
> +common_type *p = ....;
> +if (specific_type *q = p-&gt;to_specific ()) {
> +  // We have and can use a specific_type pointed to by q.
> +}
> +</code></pre></blockquote>

This is basically equivalent to dynamic_cast except that you need to 
clutter up your root base class with one virtual function for each 
derived class you want to be able to convert to.

Jason
Benjamin Kosnik - June 26, 2012, 4:44 p.m.
> 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.

This seems to be what reliably happens in libstdc++-land. 

-benjamin
Lawrence Crowl - June 26, 2012, 5:59 p.m.
On 6/25/12, Alexandre Oliva <aoliva@redhat.com> wrote:
> On Jun 25, 2012, Lawrence Crowl <crowl@google.com> wrote:
>> +These conventions will change over time,
>> +but changing them requires that a convincing rationale.
>
> s/that//
>
>> +Complex heirarchies are to be avoided.
>
> s/heir/hier/

Both fixed.
Lawrence Crowl - June 26, 2012, 6:06 p.m.
On 6/26/12, Martin Jambor <mjambor@suse.cz> wrote:
> On Mon, Jun 25, 2012 at 03:26:01PM -0700, Lawrence Crowl wrote:
> > > I have no idea.  I don't use emacs.  The two-space rule for
> > > members comes from the wiki.  The one-space rule for protection
> > > labels is common practice.  If folks want something else,
> > > changes are fine with me.
>
> I'll also need an emacs C++ indentation style that conforms to
> this in order to really be able to produce complying code myself.
> So if anybody else will be working on that, I'm interested (to
> use it and perhaps help crafting it) and I guess a number of
> other people on this list are too...

Alternatively, one could change the conventions to match an emacs
style.  Either is fine we me, as long as the style is reasonable.

> > -<h2>Miscellaneous Conventions</h2>
> > -
> > -<p>Code should use <code>gcc_assert(EXPR)</code> to check invariants.
> > -Use <code>gcc_unreachable()</code> to mark places that should never be
> > -reachable (such as an unreachable <code>default</code> case of a
> > -switch).  Do not use <code>gcc_assert(0)</code> for such purposes, as
> > -<code>gcc_unreachable</code> gives the compiler more information.  The
> > -assertions are enabled unless explicitly configured off with
> > -<code>--enable-checking=none</code>.  Do not use <code>abort</code>.
> > -User input should never be validated by either <code>gcc_assert</code>
> > -or <code>gcc_unreachable</code>.  If the checks are expensive or the
> > -compiler can reasonably carry on after the error, they may be
> > -conditioned on <code>--enable-checking</code>.</p>
>
> It seems we should mention gcc_checking_assert here then.

Jason had a suggestion, and I used that.

> > +<p>
> > +Single inheritance is permitted.
> > +Use public inheritance to describe interface inheritance,
> > +i.e. 'is-a' relationships.
> > +Use private and protected inheritance
> > +to describe implementation inheritance.
> > +Implementation inheritance can be expediant,

> s/expediant/expedient/

Fixed.

> > +but think twice before using it in code
> > +intended to last a long time.
>
> I think all committed code should be expected to have long-lasting
> quality.  I would not encourage people to think otherwise and would
> drop the "long time" reference here.  If anybody ever commits
> something ugly to bridge a short time period, it should only be done
> under the "maintainers grant exceptions" rule anyway.
>
> > +</p>> +<p>
> > +For long-term code, at least for now,
> > +we will continue to use <code>printf</code> style I/O
> > +rather than <code>&lt;iostream&gt;</code> style I/O.
> > +For quick debugging code,
> > +<code>&lt;iostream&gt;</code> is permitted.
> > +</p>
>
> Similarly here, no quick and dirty debugging output should ever be
> committed, we should not
>
> > +<h4><a name="stdlib">The Standard Library</a></h4>
> > +
> > +<p>
> > +At present, C++ provides no great advantage for i18n.
> > +GCC does type checking for <code>printf</code> arguments,
> > +so the type insecurity of <code>printf</code> is moot,
> > +but the clarity in layout persists.
> > +For quick debugging output, &lt;iostream&gt; requires less work.
> > +</p>
>
> The same applies here.

The value of these changes depends on when the rules are enforced.
If they are enforced only on trunk, then the changes seem fine
to me.  However, if they are enforced on branches, then they could
unnecessarily slow down development.

Comments?
Lawrence Crowl - June 26, 2012, 6:19 p.m.
On 6/26/12, Jason Merrill <jason@redhat.com> wrote:
> On 06/25/2012 06:26 PM, Lawrence Crowl wrote:
> > +or<code>gcc_unreachable</code>.  If the checks are expensive or the
> > +compiler can reasonably carry on after the error, they may be
> > +conditioned on<code>--enable-checking</code>.</p>
>
> by using <code>gcc_checking_assert</code>

I inserted that suggestion, but note that I did not create that text,
only moved it.

> [Rationale]
> > +FIXME: Discussion of deleting inappropraite special members.
>
> Is this FIXME still needed?  The text following it seems to cover the
> issue well enough.

No longer needed.

> > +However, by default, RTTI is not permitted
> > +and the compiler must build cleanly with <code>-fno-rtti</code>.
>
> This seems like an unnecessary restriction to me.
>
> > +Disabling RTTI will save space in the compiler.
>
> This is a fine reason to disable RTTI if it isn't used, but doesn't
> seem like a strong reason to prohibit using it.  The information is
> only emitted for classes with virtual functions, isn't very large,
> is typically emitted in only one object file, and since it lives
> in .rodata it can be shared between multiple compiler processes.
>
> > +Checking the type of a class at runtime usually indicates a design problem.
>
> The tree_contains_struct machinery recently added to GCC maps
> directly onto dynamic_cast;
>
> if (CODE_CONTAINS_STRUCT(TREE_CODE(t),TS_DECL_WRTL))
>   /* do something with t->decl_with_rtl */
>
> translates roughly to to
>
> if (decl_with_rtl *p = dynamic_cast <decl_with_rtl *>(t))
>   /* do something with p */
>
> When new interfaces are added partway down an inheritance tree,
> dynamic_cast is the right way to access them.  This isn't checking
> what the type is, it's checking whether the object supports a
> particular method.
>
> The fact that we've gone to the trouble to implement this
> functionality in C suggests to me that using it isn't always
> indicative of a design problem.  :)

Personally, I am fine with using dynamic_cast.  I was writing up what
I thought was a consensus on the wiki.  I can live without it, or I
can use it profitably.  Whatever you all decide, I will write up.

> > +If you need to know the type of a class for some other reason,
> > +use an enum or a virtual member function
> > +that coverts a pointer to the more derived class.
> > +For example,
> > +</p>
> > +
> > +<blockquote><pre><code>
> > +common_type *p = ....;
> > +if (specific_type *q = p-&gt;to_specific ()) {
> > +  // We have and can use a specific_type pointed to by q.
> > +}
> > +</code></pre></blockquote>
>
> This is basically equivalent to dynamic_cast except that you need
> to clutter up your root base class with one virtual function for
> each derived class you want to be able to convert to.

Note quite equivalent, as you can implement to_specific with
non-virtual classes using the TREE_CODE.  Thus would could implement
a type-save dynamic pointer converter before converting to virtual
classes.

OTOH, we could probably work up a template function that looks like
dynamic_cast but uses the TREE_CODE instead, achieving the same
intermediate step.

I agree that it does clutter up the base class.

Shall we enable RTTI?
Gabriel Dos Reis - June 26, 2012, 6:24 p.m.
Lawrence Crowl <crowl@google.com> writes:

[...]

| Shall we enable RTTI?

Benjamin made compelling arguments for doing this.  And I agree.

-- Gaby
Joseph S. Myers - June 26, 2012, 6:47 p.m.
On Tue, 26 Jun 2012, Lawrence Crowl wrote:

> Shall we enable RTTI?

I think any proposal for adding a new C++ feature to the standards should 
go in its own thread on the gcc list with a meaningful subject, not this 
thread which should simply be about integrating uncontroversial standards 
in the existing documents.

We should start by documenting standards that are a conservative and 
uncontroversial extension of the C coding standards currently used - if we 
need to ask the question about whether something should be allowed, it 
should not be allowed in the initial standards coming out of this general 
thread.  Then, to add individual features to the list we can discuss those 
features and standards for them separately.
Jason Merrill - June 26, 2012, 6:55 p.m.
On 06/26/2012 02:47 PM, Joseph S. Myers wrote:
> We should start by documenting standards that are a conservative and
> uncontroversial extension of the C coding standards currently used - if we
> need to ask the question about whether something should be allowed, it
> should not be allowed in the initial standards coming out of this general
> thread.

Sure; I don't mind initially disabling RTTI with a note that someone 
wanting to use it is free to propose adding it to the coding standards. 
  I was mainly objecting to the rationale.

Jason
Mike Stump - June 26, 2012, 8:42 p.m.
On Jun 26, 2012, at 11:06 AM, Lawrence Crowl wrote:
> Alternatively, one could change the conventions to match an emacs
> style.  Either is fine we me, as long as the style is reasonable.

It is really nice to be able to use 5 year old emacsen out of the box on the source tree and have it just work.  I'd vote for that...
Chiheng Xu - June 27, 2012, 12:35 p.m.
On Wed, Jun 27, 2012 at 2:19 AM, Lawrence Crowl <crowl@google.com> wrote:
> On 6/26/12, Jason Merrill <jason@redhat.com> wrote:
>> On 06/25/2012 06:26 PM, Lawrence Crowl wrote:
>> > +or<code>gcc_unreachable</code>.  If the checks are expensive or the
>> > +compiler can reasonably carry on after the error, they may be
>> > +conditioned on<code>--enable-checking</code>.</p>
>>
>> by using <code>gcc_checking_assert</code>
>
> I inserted that suggestion, but note that I did not create that text,
> only moved it.
>
>> [Rationale]
>> > +FIXME: Discussion of deleting inappropraite special members.
>>
>> Is this FIXME still needed?  The text following it seems to cover the
>> issue well enough.
>
> No longer needed.
>
>> > +However, by default, RTTI is not permitted
>> > +and the compiler must build cleanly with <code>-fno-rtti</code>.
>>
>> This seems like an unnecessary restriction to me.
>>
>> > +Disabling RTTI will save space in the compiler.
>>
>> This is a fine reason to disable RTTI if it isn't used, but doesn't
>> seem like a strong reason to prohibit using it.  The information is
>> only emitted for classes with virtual functions, isn't very large,
>> is typically emitted in only one object file, and since it lives
>> in .rodata it can be shared between multiple compiler processes.
>>
>> > +Checking the type of a class at runtime usually indicates a design problem.
>>
>> The tree_contains_struct machinery recently added to GCC maps
>> directly onto dynamic_cast;
>>
>> if (CODE_CONTAINS_STRUCT(TREE_CODE(t),TS_DECL_WRTL))
>>   /* do something with t->decl_with_rtl */
>>
>> translates roughly to to
>>
>> if (decl_with_rtl *p = dynamic_cast <decl_with_rtl *>(t))
>>   /* do something with p */
>>
>> When new interfaces are added partway down an inheritance tree,
>> dynamic_cast is the right way to access them.  This isn't checking
>> what the type is, it's checking whether the object supports a
>> particular method.
>>
>> The fact that we've gone to the trouble to implement this
>> functionality in C suggests to me that using it isn't always
>> indicative of a design problem.  :)
>
> Personally, I am fine with using dynamic_cast.  I was writing up what
> I thought was a consensus on the wiki.  I can live without it, or I
> can use it profitably.  Whatever you all decide, I will write up.
>

dynamic_cast use RTTI, while TREE_CODE are poor man's type info. RTTI
is better than TREE_CODE. But, If you decide to use RTTI,  TREE_CODE
become redundant, that means all use of TREE_CODE should be removed,
sooner or later. Are you prepared for that ?

If every types in the type hierarchy, not just the root type and
leaves types,  has a TREE_CODE,  and you maintain a database of
inheritance relationship and other info of types of different
TREE_CODEs,  then,  for a object of a given TREE_CODE,  you know its
TREE_CODE and type info,   you know whether or not the object can be
cast to another type,  and,  you can know other info about the type,
like the size of object of the type, string name of the type.

This can be implemented as below. For every type in the type
hierarchy, static define a object of meta type( meta class, or class
class) to describe the type info of the specific type for a given
TREE_CODE. All of the meta type objects of different TREE_CODEs are
organized as an array, which is indexed by the value of TREE_CODE. And
you provide a set of C functions , that judge whether a object that
has a given TREE_CODE can be cast to a type that has another TREE_CODE
and retrieve the type info of a object that has a given TREE_CODE.


>> > +If you need to know the type of a class for some other reason,
>> > +use an enum or a virtual member function
>> > +that coverts a pointer to the more derived class.
>> > +For example,
>> > +</p>
>> > +
>> > +<blockquote><pre><code>
>> > +common_type *p = ....;
>> > +if (specific_type *q = p-&gt;to_specific ()) {
>> > +  // We have and can use a specific_type pointed to by q.
>> > +}
>> > +</code></pre></blockquote>
>>
>> This is basically equivalent to dynamic_cast except that you need
>> to clutter up your root base class with one virtual function for
>> each derived class you want to be able to convert to.
>
> Note quite equivalent, as you can implement to_specific with
> non-virtual classes using the TREE_CODE.  Thus would could implement
> a type-save dynamic pointer converter before converting to virtual
> classes.
>
> OTOH, we could probably work up a template function that looks like
> dynamic_cast but uses the TREE_CODE instead, achieving the same
> intermediate step.
>
> I agree that it does clutter up the base class.
>

Template function may be not necessary.
And, virtual method is not necessary.
Just normal C functions can work if you have the type info of a given TREE_CODE.

> Shall we enable RTTI?
Are you prepared to remove all use of TREE_CODE ?
Richard Guenther - June 27, 2012, 1:02 p.m.
On Wed, Jun 27, 2012 at 2:35 PM, Chiheng Xu <chiheng.xu@gmail.com> wrote:
> On Wed, Jun 27, 2012 at 2:19 AM, Lawrence Crowl <crowl@google.com> wrote:
>> On 6/26/12, Jason Merrill <jason@redhat.com> wrote:
>>> On 06/25/2012 06:26 PM, Lawrence Crowl wrote:
>>> > +or<code>gcc_unreachable</code>.  If the checks are expensive or the
>>> > +compiler can reasonably carry on after the error, they may be
>>> > +conditioned on<code>--enable-checking</code>.</p>
>>>
>>> by using <code>gcc_checking_assert</code>
>>
>> I inserted that suggestion, but note that I did not create that text,
>> only moved it.
>>
>>> [Rationale]
>>> > +FIXME: Discussion of deleting inappropraite special members.
>>>
>>> Is this FIXME still needed?  The text following it seems to cover the
>>> issue well enough.
>>
>> No longer needed.
>>
>>> > +However, by default, RTTI is not permitted
>>> > +and the compiler must build cleanly with <code>-fno-rtti</code>.
>>>
>>> This seems like an unnecessary restriction to me.
>>>
>>> > +Disabling RTTI will save space in the compiler.
>>>
>>> This is a fine reason to disable RTTI if it isn't used, but doesn't
>>> seem like a strong reason to prohibit using it.  The information is
>>> only emitted for classes with virtual functions, isn't very large,
>>> is typically emitted in only one object file, and since it lives
>>> in .rodata it can be shared between multiple compiler processes.
>>>
>>> > +Checking the type of a class at runtime usually indicates a design problem.
>>>
>>> The tree_contains_struct machinery recently added to GCC maps
>>> directly onto dynamic_cast;
>>>
>>> if (CODE_CONTAINS_STRUCT(TREE_CODE(t),TS_DECL_WRTL))
>>>   /* do something with t->decl_with_rtl */
>>>
>>> translates roughly to to
>>>
>>> if (decl_with_rtl *p = dynamic_cast <decl_with_rtl *>(t))
>>>   /* do something with p */
>>>
>>> When new interfaces are added partway down an inheritance tree,
>>> dynamic_cast is the right way to access them.  This isn't checking
>>> what the type is, it's checking whether the object supports a
>>> particular method.
>>>
>>> The fact that we've gone to the trouble to implement this
>>> functionality in C suggests to me that using it isn't always
>>> indicative of a design problem.  :)
>>
>> Personally, I am fine with using dynamic_cast.  I was writing up what
>> I thought was a consensus on the wiki.  I can live without it, or I
>> can use it profitably.  Whatever you all decide, I will write up.
>>
>
> dynamic_cast use RTTI, while TREE_CODE are poor man's type info. RTTI
> is better than TREE_CODE.

RTTI requires more space than TREE_CODE, so it's not universally better.

> But, If you decide to use RTTI,  TREE_CODE
> become redundant, that means all use of TREE_CODE should be removed,
> sooner or later. Are you prepared for that ?
>
> If every types in the type hierarchy, not just the root type and
> leaves types,  has a TREE_CODE,  and you maintain a database of
> inheritance relationship and other info of types of different
> TREE_CODEs,  then,  for a object of a given TREE_CODE,  you know its
> TREE_CODE and type info,   you know whether or not the object can be
> cast to another type,  and,  you can know other info about the type,
> like the size of object of the type, string name of the type.
>
> This can be implemented as below. For every type in the type
> hierarchy, static define a object of meta type( meta class, or class
> class) to describe the type info of the specific type for a given
> TREE_CODE. All of the meta type objects of different TREE_CODEs are
> organized as an array, which is indexed by the value of TREE_CODE. And
> you provide a set of C functions , that judge whether a object that
> has a given TREE_CODE can be cast to a type that has another TREE_CODE
> and retrieve the type info of a object that has a given TREE_CODE.

We already have all (or most) of this.

>>> > +If you need to know the type of a class for some other reason,
>>> > +use an enum or a virtual member function
>>> > +that coverts a pointer to the more derived class.
>>> > +For example,
>>> > +</p>
>>> > +
>>> > +<blockquote><pre><code>
>>> > +common_type *p = ....;
>>> > +if (specific_type *q = p-&gt;to_specific ()) {
>>> > +  // We have and can use a specific_type pointed to by q.
>>> > +}
>>> > +</code></pre></blockquote>
>>>
>>> This is basically equivalent to dynamic_cast except that you need
>>> to clutter up your root base class with one virtual function for
>>> each derived class you want to be able to convert to.
>>
>> Note quite equivalent, as you can implement to_specific with
>> non-virtual classes using the TREE_CODE.  Thus would could implement
>> a type-save dynamic pointer converter before converting to virtual
>> classes.
>>
>> OTOH, we could probably work up a template function that looks like
>> dynamic_cast but uses the TREE_CODE instead, achieving the same
>> intermediate step.
>>
>> I agree that it does clutter up the base class.
>>
>
> Template function may be not necessary.
> And, virtual method is not necessary.
> Just normal C functions can work if you have the type info of a given TREE_CODE.
>
>> Shall we enable RTTI?
> Are you prepared to remove all use of TREE_CODE ?

To answer, no - we should not enable RTTI (nor exceptions).

Richard.
Martin Jambor - June 27, 2012, 1:21 p.m.
Hi,

On Tue, Jun 26, 2012 at 11:06:15AM -0700, Lawrence Crowl wrote:
> On 6/26/12, Martin Jambor <mjambor@suse.cz> wrote:
> > On Mon, Jun 25, 2012 at 03:26:01PM -0700, Lawrence Crowl wrote:
> > > > I have no idea.  I don't use emacs.  The two-space rule for
> > > > members comes from the wiki.  The one-space rule for protection
> > > > labels is common practice.  If folks want something else,
> > > > changes are fine with me.
> >
> > I'll also need an emacs C++ indentation style that conforms to
> > this in order to really be able to produce complying code myself.
> > So if anybody else will be working on that, I'm interested (to
> > use it and perhaps help crafting it) and I guess a number of
> > other people on this list are too...
> 
> Alternatively, one could change the conventions to match an emacs
> style.  Either is fine we me, as long as the style is reasonable.

That would be very nice :-) 
Of course, if many people do not find it reasonable, I'm sure there is
an easy way to tweak it.

...

> > > +but think twice before using it in code
> > > +intended to last a long time.
> >
> > I think all committed code should be expected to have long-lasting
> > quality.  I would not encourage people to think otherwise and would
> > drop the "long time" reference here.  If anybody ever commits
> > something ugly to bridge a short time period, it should only be done
> > under the "maintainers grant exceptions" rule anyway.
> >
> > > +</p>> +<p>
> > > +For long-term code, at least for now,
> > > +we will continue to use <code>printf</code> style I/O
> > > +rather than <code>&lt;iostream&gt;</code> style I/O.
> > > +For quick debugging code,
> > > +<code>&lt;iostream&gt;</code> is permitted.
> > > +</p>
> >
> > Similarly here, no quick and dirty debugging output should ever be
> > committed, we should not
> >
> > > +<h4><a name="stdlib">The Standard Library</a></h4>
> > > +
> > > +<p>
> > > +At present, C++ provides no great advantage for i18n.
> > > +GCC does type checking for <code>printf</code> arguments,
> > > +so the type insecurity of <code>printf</code> is moot,
> > > +but the clarity in layout persists.
> > > +For quick debugging output, &lt;iostream&gt; requires less work.
> > > +</p>
> >
> > The same applies here.
> 
> The value of these changes depends on when the rules are enforced.
> If they are enforced only on trunk, then the changes seem fine
> to me.  However, if they are enforced on branches, then they could
> unnecessarily slow down development.
> 
> Comments?

I think that if you have a private branch, you are basically its
maintainer and can grant yourself any exception from any rule you
want.  Of course, that might make your life harder if you later want
to contribute the changes to the trunk, release branches, other
peple's branches and generally anywhere.

Thanks,

Martin
Jason Merrill - June 27, 2012, 1:41 p.m.
On 06/27/2012 08:35 AM, Chiheng Xu wrote:
> dynamic_cast use RTTI, while TREE_CODE are poor man's type info. RTTI
> is better than TREE_CODE. But, If you decide to use RTTI,  TREE_CODE
> become redundant, that means all use of TREE_CODE should be removed,
> sooner or later. Are you prepared for that ?

I wasn't suggesting we would change trees to use inheritance in the 
forseeable future; my point was that RTTI is used in patterns like what 
we already do with trees, so I don't think that using it indicates a 
design problem.

If we were to change trees to use inheritance and virtual functions, 
which seems unlikely to me, then I think it would make sense to use RTTI 
instead of TREE_CODE.

On 06/27/2012 09:02 AM, Richard Guenther wrote:
> RTTI requires more space than TREE_CODE, so it's not universally better.

RTTI requires no additional space in each object, and no space at all 
for classes with no virtual functions.

> To answer, no - we should not enable RTTI (nor exceptions).

The problem with exceptions is that the compiler is not exception-safe. 
  I don't think there's a good reason to prohibit RTTI.  As I said in 
another message, I don't mind turning it off for now, but I don't think 
doing so has much benefit either, since it only affects classes with 
virtual functions.

Jason
Lawrence Crowl - June 28, 2012, 1:55 a.m.
On 6/27/12, Martin Jambor <mjambor@suse.cz> wrote:
> On Tue, Jun 26, 2012 at 11:06:15AM -0700, Lawrence Crowl wrote:
> > On 6/26/12, Martin Jambor <mjambor@suse.cz> wrote:
> > > On Mon, Jun 25, 2012 at 03:26:01PM -0700, Lawrence Crowl wrote:
> > > > +but think twice before using it in code
> > > > +intended to last a long time.
> > >
> > > I think all committed code should be expected to have
> > > long-lasting quality.  I would not encourage people to think
> > > otherwise and would drop the "long time" reference here.
> > > If anybody ever commits something ugly to bridge a short time
> > > period, it should only be done under the "maintainers grant
> > > exceptions" rule anyway.
> > >
> > > > +</p>> +<p>
> > > > +For long-term code, at least for now,
> > > > +we will continue to use <code>printf</code> style I/O
> > > > +rather than <code>&lt;iostream&gt;</code> style I/O.
> > > > +For quick debugging code,
> > > > +<code>&lt;iostream&gt;</code> is permitted.
> > > > +</p>
> > >
> > > Similarly here, no quick and dirty debugging output should
> > > ever be committed, we should not
> > >
> > > > +<h4><a name="stdlib">The Standard Library</a></h4>
> > > > +
> > > > +<p>
> > > > +At present, C++ provides no great advantage for i18n.
> > > > +GCC does type checking for <code>printf</code> arguments,
> > > > +so the type insecurity of <code>printf</code> is moot,
> > > > +but the clarity in layout persists.
> > > > +For quick debugging output, &lt;iostream&gt; requires less work.
> > > > +</p>
> > >
> > > The same applies here.
> >
> > The value of these changes depends on when the rules are
> > enforced.  If they are enforced only on trunk, then the changes
> > seem fine to me.  However, if they are enforced on branches,
> > then they could unnecessarily slow down development.
> >
> > Comments?
>
> I think that if you have a private branch, you are basically
> its maintainer and can grant yourself any exception from any
> rule you want.  Of course, that might make your life harder if
> you later want to contribute the changes to the trunk, release
> branches, other peple's branches and generally anywhere.

I am not concerned about private branches, but public branches for
which sharing might be needed, but for which cleanup before going
into trunk or a release is reasonable.

C++ streams are much more convenient for free-form output than
C-based solutions.  Having said that, does anyone object to removing
the permission to use C++ streams?

Patch

Index: htdocs/codingconventions.html
===================================================================
RCS file: /cvs/gcc/wwwdocs/htdocs/codingconventions.html,v
retrieving revision 1.66
diff -u -u -r1.66 codingconventions.html
--- htdocs/codingconventions.html	19 Feb 2012 00:45:34 -0000	1.66
+++ htdocs/codingconventions.html	25 Jun 2012 22:19:46 -0000
@@ -15,8 +19,71 @@ 
 code to follow these conventions, it is best to send changes to follow
 the conventions separately from any other changes to the code.</p>

+<ul>
+<li><a href="#Documentation">Documentation</a></li>
+<li><a href="#ChangeLogs">ChangeLogs</a></li>
+<li><a href="#Portability">Portability</a></li>
+<li><a href="#Makefiles">Makefiles</a></li>
+<li><a href="#Testsuite">Testsuite Conventions</a></li>
+<li><a href="#Diagnostics">Diagnostics Conventions</a></li>
+<li><a href="#Spelling">Spelling, terminology and markup</a></li>
+<li><a href="#CandCxx">C and C++ Language Conventions</a>
+    <ul>
+    <li><a href="#C_Options">Compiler Options</a></li>
+    <li><a href="#C_Language">Language Use</a>
+        <ul>
+        <li><a href="#Assertions">Assertions</a></li>
+        <li><a href="#Character">Character Testing</a></li>
+        <li><a href="#Error">Error Node Testing</a></li>
+        <li><a href="#Generated">Parameters Affecting Generated Code</a></li>
+        <li><a href="#C_Inlining">Inlining Functions</a></li>
+        </ul>
+    </li>
+    <li><a href="#C_Formatting">Formatting Conventions</a>
+        <ul>
+        <li><a href="#Line">Line Length</a></li>
+        <li><a href="#C_Names">Names</a></li>
+        <li><a href="#Expressions">Expressions</a></li>
+        </ul>
+    </li>
+    </ul>
+</li>
+<li><a href="#Cxx_Conventions">C++ Language Conventions</a>
+    <ul>
+    <li><a href="#Cxx_Language">Language Use</a>
+        <ul>
+        <li><a href="#Variable">Variable Definitions</a></li>
+        <li><a href="#Struct_Use">Struct Definitions</a></li>
+        <li><a href="#Class_Use">Class Definitions</a></li>
+        <li><a href="#Constructors">Constructors and Destructors</a></li>
+        <li><a href="#Conversions">Conversions</a></li>
+        <li><a href="#Over_Func">Overloading Functions</a></li>
+        <li><a href="#Over_Oper">Overloading Operators</a></li>
+        <li><a href="#Default">Default Arguments</a></li>
+        <li><a href="#Cxx_Inlining">Inlining Functions</a></li>
+        <li><a href="#Template_Use">Templates</a></li>
+        <li><a href="#Namespace_Use">Namespaces</a></li>
+        <li><a href="#RTTI">RTTI and <code>dynamic_cast</code></a></li>
+        <li><a href="#Casts">Other Casts</a></li>
+        <li><a href="#Exceptions">Exceptions</a></li>
+        <li><a href="#Standard_Library">The Standard Library</a></li>
+        </ul>
+    </li>
+    <li><a href="#Cxx_Formatting">Formatting Conventions</a></li>
+        <ul>
+        <li><a href="#Cxx_Names">Names</a></li>
+        <li><a href="#Struct_Form">Struct Definitions</a></li>
+        <li><a href="#Class_Form">Class Definitions</a></li>
+        <li><a href="#Member_Form">Class Member Definitions</a></li>
+        <li><a href="#Template_Form">Templates</a></li>
+        <li><a href="#ExternC">Extern "C"</a></li>
+        <li><a href="#Namespace_Form">Namespaces</a></li>
+        </ul>
+    </li>
+</ul>

-<h2>Documentation</h2>
+
+<h2><a name="Documentation">Documentation</a></h2>

 <p>Documentation, both of user interfaces and of internals, must be
 maintained and kept up to date.  In particular:</p>
@@ -43,7 +110,7 @@ 
 </ul>


-<h2>ChangeLogs</h2>
+<h2><a name="ChangeLogs">ChangeLogs</a></h2>

 <p>GCC requires ChangeLog entries for documentation changes; for the web
 pages (apart from <code>java/</code> and <code>libstdc++/</code>) the CVS
@@ -71,20 +138,40 @@ 
 <code>java/58</code> is the actual number of the PR) at the top
 of the ChangeLog entry.</p>

-<h2>Portability</h2>
+<h2><a name="Portability">Portability</a></h2>

 <p>There are strict requirements for portability of code in GCC to
-older systems whose compilers do not implement all of the ISO C standard.
-GCC requires at least an ANSI C89 or ISO C90 host compiler, and code
-should avoid pre-standard style function definitions, unnecessary
-function prototypes and use of the now deprecated @code{PARAMS} macro.
+older systems whose compilers do not implement all of the
+latest ISO C and C++ standards.
+</p>
+
+<p>
+The directories
+<code>gcc</code>, <code>libcpp</code> and <code>fixincludes</code>
+may use C++03.
+They may also use the <code>long long</code> type
+if the host C++ compiler supports it.
+These directories should use reasonably portable parts of C++03,
+so that it is possible to build GCC with C++ compilers other than GCC itself.
+If testing reveals that
+reasonably recent versions of non-GCC C++ compilers cannot compile GCC,
+then GCC code should be adjusted accordingly.
+(Avoiding unusual language constructs helps immensely.)
+Furthermore,
+these directories <em>should</em> also be compatible with C++11.
+</p>
+
+<p>
+The directories libiberty and libdecnumber must use C
+and require at least an ANSI C89 or ISO C90 host compiler.
+C code should avoid pre-standard style function definitions, unnecessary
+function prototypes and use of the now deprecated <code>PARAMS</code> macro.
 See <a
 href="http://gcc.gnu.org/cgi-bin/cvsweb.cgi/~checkout~/gcc/gcc/README.Portability?content-type=text/plain&amp;only_with_tag=HEAD">README.Portability</a>
 for details of some of the portability problems that may arise.  Some
 of these problems are warned about by <code>gcc -Wtraditional</code>,
 which is included in the default warning options in a bootstrap.
-(Code outside the C front end is only compiled by GCC, so such
-requirements do not apply to it.)</p>
+</p>

 <p>The programs included in GCC are linked with the
 libiberty library, which will replace some standard
@@ -108,12 +195,6 @@ 
 the release cycle, to reduce the risk involved in fixing a problem
 that only shows up on one particular system.</p>

-<p>Avoid the use of identifiers or idioms that would prevent code
-compiling with a C++ compiler.  Identifiers such as <code>new</code>
-or <code>class</code>, that are reserved words in C++, should not be
-used as variables or field names.  Explicit casts should be used to
-convert between <code>void*</code> and other pointer types.</p>
-
 <p>Function prototypes for extern functions should only occur in
 header files.  Functions should be ordered within source files to
 minimize the number of function prototypes, by defining them before
@@ -121,13 +202,13 @@ 
 necessary, to break mutually recursive cycles.</p>


-<h2>Makefiles</h2>
+<h2><a name="Makefiles">Makefiles</a></h2>

 <p><code>touch</code> should never be used in GCC Makefiles.  Instead
 of <code>touch foo</code> always use <code>$(STAMP) foo</code>.</p>


-<h2>Testsuite Conventions</h2>
+<h2><a name="Testsuite">Testsuite Conventions</a></h2>

 <p>Every language or library feature, whether standard or a GNU
 extension, and every warning GCC can give, should have testcases
@@ -157,7 +238,7 @@ 
 to the test suite.</p>


-<h2>Diagnostics Conventions</h2>
+<h2><a name="Diagnostics">Diagnostics Conventions</a></h2>
 <ul>

 <li>Use of the <code>input_location</code> global, and of the
@@ -208,66 +289,7 @@ 
 </ul>


-<h2>Miscellaneous Conventions</h2>
-
-<p>Code should use <code>gcc_assert(EXPR)</code> to check invariants.
-Use <code>gcc_unreachable()</code> to mark places that should never be
-reachable (such as an unreachable <code>default</code> case of a
-switch).  Do not use <code>gcc_assert(0)</code> for such purposes, as
-<code>gcc_unreachable</code> gives the compiler more information.  The
-assertions are enabled unless explicitly configured off with
-<code>--enable-checking=none</code>.  Do not use <code>abort</code>.
-User input should never be validated by either <code>gcc_assert</code>
-or <code>gcc_unreachable</code>.  If the checks are expensive or the
-compiler can reasonably carry on after the error, they may be
-conditioned on <code>--enable-checking</code>.</p>
-
-<p>Code testing properties of characters from user source code should
-use macros such as <code>ISALPHA</code> from <code>safe-ctype.h</code>
-instead of the standard functions such as <code>isalpha</code> from
-<code>&lt;ctype.h&gt;</code> to avoid any locale-dependency of the
-language accepted.</p>
-
-<p>Code in GCC should use the following formatting conventions:</p>
-
-<table cellpadding="4">
-<tr>
-  <th align="right">Use...</th><th align="left">...instead of</th>
-</tr><tr>
-  <td align="right"><code>!x</code></td><td><code>! x</code></td>
-</tr><tr>
-  <td align="right"><code>~x</code></td><td><code>~ x</code></td>
-</tr><tr>
-  <td align="right"><code>-x</code> (unary minus)</td><td><code>- x</code></td>
-</tr><tr>
-  <td align="right"><code>(foo) x</code> (cast)</td>
-  <td><code>(foo)x</code></td>
-</tr><tr>
-  <td align="right"><code>*x</code> (pointer dereference)</td>
-  <td><code>* x</code></td>
-</tr>
-</table>
-
-
-<p>Macros names should be in <code>ALL_CAPS</code> when it's important
-to be aware that it's a macro (e.g. accessors and simple predicates),
-but in lowercase (e.g., <code>size_int</code>) where the macro is a
-wrapper for efficiency that should be considered as a function; see
-messages <a
-href="http://gcc.gnu.org/ml/gcc-patches/2000-09/msg00901.html">1</a>
-and <a
-href="http://gcc.gnu.org/ml/gcc-patches/2000-09/msg00912.html">2</a>.</p>
-
-<p>Testing for <code>ERROR_MARK</code>s should be done by comparing
-against <code>error_mark_node</code> rather than by comparing the
-<code>TREE_CODE</code> against <code>ERROR_MARK</code>; see <a
-href="http://gcc.gnu.org/ml/gcc-patches/2000-10/msg00792.html">message</a>.</p>
-
-<p>Internal numeric parameters that may affect generated code should
-be controlled by <code>--param</code> rather than being hardcoded.</p>
-
-
-<h2>Spelling, terminology and markup</h2>
+<h2><a name="Spelling">Spelling, terminology and markup</a></h2>

 <p>The following conventions of spelling and terminology apply
 throughout GCC, including the manuals, web pages, diagnostics,
@@ -645,5 +667,668 @@ 

 </ul>

+
+<h2><a name="CandCxx">C and C++ Language Conventions</a></h2>
+
+<p>
+The following conventions apply to both C and C++.
+</p>
+
+
+<h3><a name="C_Options">Compiler Options</a></h3>
+
+<p>
+The compiler must build cleanly with <code>-Wall -Wextra</code>.
+</p>
+
+
+<h3><a name="C_Language">Language Use</a></h3>
+
+
+<h4><a name="Assertions">Assertions</a></h4>
+
+<p>Code should use <code>gcc_assert(EXPR)</code> to check invariants.
+Use <code>gcc_unreachable()</code> to mark places that should never be
+reachable (such as an unreachable <code>default</code> case of a
+switch).  Do not use <code>gcc_assert(0)</code> for such purposes, as
+<code>gcc_unreachable</code> gives the compiler more information.  The
+assertions are enabled unless explicitly configured off with
+<code>--enable-checking=none</code>.  Do not use <code>abort</code>.
+User input should never be validated by either <code>gcc_assert</code>
+or <code>gcc_unreachable</code>.  If the checks are expensive or the
+compiler can reasonably carry on after the error, they may be
+conditioned on <code>--enable-checking</code>.</p>
+
+
+<h4><a name="Character">Character Testing</a></h4>
+
+<p>Code testing properties of characters from user source code should
+use macros such as <code>ISALPHA</code> from <code>safe-ctype.h</code>
+instead of the standard functions such as <code>isalpha</code> from
+<code>&lt;ctype.h&gt;</code> to avoid any locale-dependency of the
+language accepted.</p>
+
+
+<h4><a name="Error">Error Node Testing</a></h4>
+
+<p>Testing for <code>ERROR_MARK</code>s should be done by comparing
+against <code>error_mark_node</code> rather than by comparing the
+<code>TREE_CODE</code> against <code>ERROR_MARK</code>; see <a
+href="http://gcc.gnu.org/ml/gcc-patches/2000-10/msg00792.html">message</a>.</p>
+
+
+<h4><a name="Generated">Parameters Affecting Generated Code</a></h4>
+
+<p>Internal numeric parameters that may affect generated code should
+be controlled by <code>--param</code> rather than being hardcoded.</p>
+
+
+<h4><a name="C_Inlining">Inlining Functions</a></h4>
+
+<p>
+Inlining functions only when
+you have reason to believe that
+the expansion of the function is smaller than a call to the function
+or that inlining is significant to the run-time of the compiler.
+</p>
+
+
+<h3><a name="C_Formatting">Formatting Conventions</a></h3>
+
+
+<h4><a name="Line">Line Length</a></h4>
+
+<p>Lines shall be at most 80 columns.</p>
+
+
+<h4><a name="C_Names">Names</a></h4>
+
+<p>
+Macros names should be in <code>ALL_CAPS</code>
+when it's important to be aware that it's a macro
+(e.g. accessors and simple predicates),
+but in lowercase (e.g., <code>size_int</code>)
+where the macro is a wrapper for efficiency
+that should be considered as a function;
+see messages
+<a href="http://gcc.gnu.org/ml/gcc-patches/2000-09/msg00901.html">1</a>
+and <a href="http://gcc.gnu.org/ml/gcc-patches/2000-09/msg00912.html">2</a>.
+</p>
+
+<p>
+Other names should be lower-case and separated by low_lines.
+</p>
+
+
+<h4><a name="Expressions">Expressions</a></h4>
+
+<p>
+Code in GCC should use the following formatting conventions:
+</p>
+
+<table cellpadding="4">
+<tr>
+  <th align="left">For</th>
+  <th align="right">Use...</th><th align="left">...instead of</th>
+</tr><tr>
+  <td align="left">logical not</td>
+  <td align="right"><code>!x</code></td><td><code>! x</code></td>
+</tr><tr>
+  <td align="left">bitwise complement</td>
+  <td align="right"><code>~x</code></td><td><code>~ x</code></td>
+</tr><tr>
+  <td align="left">unary minus</td>
+  <td align="right"><code>-x</code></td><td><code>- x</code></td>
+</tr><tr>
+  <td align="left">cast</td>
+  <td align="right"><code>(foo) x</code></td>
+  <td><code>(foo)x</code></td>
+</tr><tr>
+  <td align="left">pointer dereference</td>
+  <td align="right"><code>*x</code></td>
+  <td><code>* x</code></td>
+</tr>
+</table>
+
+
+<h2><a name="Cxx_Conventions">C++ Language Conventions</a></h2>
+
+<p>
+The following conventions apply only to C++.
+</p>
+
+<p>
+These conventions will change over time,
+but changing them requires that a convincing rationale.
+</p>
+
+
+<h3><a name="Cxx_Language">Language Use</a></h3>
+
+<p>
+C++ is a complex language,
+and we strive to use it in a manner that is not surprising.
+So, the primary rule is to be reasonable.
+Use a language feature in known good ways.
+If you need to use a feature in an unusual way,
+or a way that violates the "should" rules below,
+seek guidance, review and feedback from the wider community.
+</p>
+
+<p>
+All use of C++ features
+is subject to the decisions of the maintainers of the relevant components.
+(This restates something that is always true for gcc,
+which is that
+component maintainers make the final decisions about those components.)
+</p>
+
+<h4><a name="Variable">Variable Definitions</a></h4>
+
+<p>
+Variables should be defined at the point of first use,
+rather than at the top of the function.
+The existing code obviously does not follow that rule,
+so variables may be defined at the top of the function,
+as in C90.
+</p>
+
+<p>
+Variables may be simultaneously defined and tested in control expressions.
+</p>
+
+<p>
+<a href="codingrationale.html#variables">Rationale and Discussion</a>
+</p>
+
+
+<h4><a name="Struct_Use">Struct Definitions</a></h4>
+
+<p>
+Use the <code>struct</code> keyword for
+<a href="http://en.wikipedia.org/wiki/Plain_old_data_structure">
+plain old data (POD)</a> types.
+</p>
+
+<p>
+<a href="codingrationale.html#struct">Rationale and Discussion</a>
+</p>
+
+<h4><a name="Class_Use">Class Definitions</a></h4>
+
+<p>
+Use the <code>class</code> keyword for
+<a href="http://en.wikipedia.org/wiki/Plain_old_data_structure">
+non-POD</a> types.
+</p>
+
+<p>
+A non-POD type will often (but not always)
+have a declaration of a
+<a href="http://en.wikipedia.org/wiki/Special_member_functions">
+special member function</a>.
+If any one of these is declared,
+then all should be either declared
+or have an explicit comment saying that the default is intended.
+</p>
+
+<p>
+Single inheritance is permitted.
+Use public inheritance to describe interface inheritance,
+i.e. 'is-a' relationships.
+Use private and protected inheritance
+to describe implementation inheritance.
+Implementation inheritance can be expediant,
+but think twice before using it in code
+intended to last a long time.
+</p>
+
+<p>
+Complex heirarchies are to be avoided.
+Take special care with multiple inheritance.
+On the rare occasion that using mulitple inheritance is indeed useful,
+prepare design rationales in advance,
+and take special care to make documentation of the entire hierarchy clear.
+</p>
+
+<p>
+Think carefully about the size and performance impact
+of virtual functions and virtual bases
+before using them.
+</p>
+
+<p>
+Prefer to make data members private.
+</p>
+
+<p>
+<a href="codingrationale.html#class">Rationale and Discussion</a>
+</p>
+
+
+<h4><a name="Constructors">Constructors and Destructors</a></h4>
+
+<p>
+All constructors should initialize data members
+in the member initializer list rather than in the body of the constructor.
+</p>
+
+<p>
+A class with virtual functions or virtual bases
+should have a virtual destructor.
+</p>
+
+<p>
+<a href="codingrationale.html#constructors">Rationale and Discussion</a>
+</p>
+
+<h4><a name="Conversions">Conversions</a></h4>
+
+<p>
+Single argument constructors should nearly always be declared explicit.
+</p>
+
+<p>
+Conversion operators should be avoided.
+</p>
+
+<p>
+<a href="codingrationale.html#conversions">Rationale and Discussion</a>
+</p>
+
+
+<h4><a name="Over_Func">Overloading Functions</a></h4>
+
+<p>
+Overloading functions is permitted,
+but take care to ensure that overloads are not surprising,
+i.e. semantically identical or at least very similar.
+Virtual functions should not be overloaded.
+</p>
+
+<p>
+<a href="codingrationale.html#overfunc">Rationale and Discussion</a>
+</p>
+
+
+<h4><a name="Over_Oper">Overloading Operators</a></h4>
+
+<p>
+Overloading operators is permitted,
+but take care to ensure that overloads are not surprising.
+Some unsurprising uses are
+in the implementation of numeric types and
+in following the C++ Standard Library's conventions.
+In addition, overloaded operators, excepting the call operator,
+should not be used for expensive implementations.
+</p>
+
+<p>
+<a href="codingrationale.html#overoper">Rationale and Discussion</a>
+</p>
+
+
+<h4><a name="Default">Default Arguments</a></h4>
+
+<p>
+Default arguments are another type of function overloading,
+and the same rules apply.
+Default arguments must always be POD values, i.e. may not run constructors.
+Virtual functions should not have default arguments.
+</p>
+
+<p>
+<a href="codingrationale.html#default">Rationale and Discussion</a>
+</p>
+
+
+<h4><a name="Cxx_Inlining">Inlining Functions</a></h4>
+
+<p>
+Constructors and destructors, even those with empty bodies,
+are often much larger than programmers expect.
+Prefer non-inline versions unless you have evidence
+that the inline version is smaller or has a significant performance impact.
+</p>
+
+
+<h4><a name="Template_Use">Templates</a></h4>
+
+<p>
+To avoid excessive compiler size,
+consider implementing non-trivial templates
+on a non-template base class with <code>void*</code> parameters.
+</p>
+
+
+<h4><a name="Namespace_Use">Namespaces</a></h4>
+
+<p>
+Namespaces are encouraged.
+All separable libraries should have a unique global namespace.
+All individual tools should have a unique global namespace.
+Nested include directories names should map to nested namespaces when
possible.
+</p>
+
+<p>
+Header files should have neither <code>using</code> directives
+nor namespace-scope <code>using</code> declarations.
+</p>
+
+<p>
+<a href="codingrationale.html#namespaces">Rationale and Discussion</a>
+</p>
+
+<h4><a name="RTTI">RTTI and <code>dynamic_cast</code></a></h4>
+
+<p>
+Run-time type information (RTTI) is permitted
+when certain non-default <code>--enable-checking</code> options are enabled,
+so as to allow checkers to report dynamic types.
+However, by default, RTTI is not permitted
+and the compiler must build cleanly with <code>-fno-rtti</code>.
+</p>
+
+<p>
+<a href="codingrationale.html#RTTI">Rationale and Discussion</a>
+</p>
+
+
+<h4><a name="Casts">Other Casts</a></h4>
+
+<p>
+C-style casts should not be used.
+Instead, use C++-style casts.
+</p>
+
+<p>
+<a href="codingrationale.html#casts">Rationale and Discussion</a>
+</p>
+
+
+<h4><a name="Exceptions">Exceptions</a></h4>
+
+<p>
+Exceptions and throw specifications are not permitted
+and the compiler must build cleanly with <code>-fno-exceptions</code>.
+</p>
+
+<p>
+<a href="codingrationale.html#exceptions">Rationale and Discussion</a>
+</p>
+
+
+<h4><a name="Standard_Library">The Standard Library</a></h4>
+
+<p>
+Use of the standard library is permitted.
+Note, however, that it is currently not usable with garbage collected data.
+</p>
+
+<p>
+For compiler messages, indeed any text that needs i18n,
+should continue to use the existing facilities.
+</p>
+
+<p>
+For long-term code, at least for now,
+we will continue to use <code>printf</code> style I/O
+rather than <code>&lt;iostream&gt;</code> style I/O.
+For quick debugging code,
+<code>&lt;iostream&gt;</code> is permitted.
+</p>
+
+<p>
+<a href="codingrationale.html#stdlib">Rationale and Discussion</a>
+</p>
+
+
+<h3><a name="Cxx_Formatting">Formatting Conventions</a></h3>
+
+
+<h4><a name="Cxx_Names">Names</a></h4>
+
+<p>
+When structs and/or classes have member functions,
+prefer to name data members with a trailing underscore.
+</p>
+
+<p>
+Template parameter names should use CamelCase,
+following the C++ Standard.
+</p>
+
+<p>
+<a href="codingrationale.html#stdlib">Rationale and Discussion</a>
+</p>
+
+
+<h4><a name="Struct_Form">Struct Definitions</a></h4>
+
+<p>
+Note that the rules for classes do not apply to structs.
+Structs continue to behave as before.
+</p>
+
+
+<h4><a name="Class_Form">Class Definitions</a></h4>
+
+<p>
+If the entire class definition fits on a single line, put it on a single line.
+Otherwise, use the following rules.
+</p>
+
+<p>
+Indent protection labels by one space.
+</p>
+
+<p>
+Indent class members by two spaces.
+</p>
+
+<p>
+Prefer to put the entire class head on a single line.
+</p>
+
+<blockquote><pre><code>
+class gnuclass : base {
+</code></pre></blockquote>
+
+<p>
+Otherwise, start the colon of the base list at the beginning of a line.
+</p>
+
+<blockquote><pre><code>
+class a_rather_long_class_name
+: with_a_very_long_base_name, and_another_just_to_make_life_hard
+{
+  int member;
+};
+</code></pre></blockquote>
+
+<p>
+If the base clause exceeds one line,
+move overflowing initializers to the next line and indent by two spaces.
+</p>
+
+<blockquote><pre><code>
+class gnuclass
+: base1 &lt;template_argument1&gt;, base2 &lt;template_argument1&gt;,
+  base3 &lt;template_argument1&gt;, base4 &lt;template_argument1&gt;
+{
+  int member;
+};
+</code></pre></blockquote>
+
+<p>
+When defining a class,
+</p>
+<ul>
+<li>first define all public types,</li>
+<li>then define all non-public types,</li>
+<li>then declare all public constructors,</li>
+<li>then declare the public destructor,</li>
+<li>then declare all public member functions,</li>
+<li>then declare all public member variables,</li>
+<li>then declare all non-public constructors,</li>
+<li>then declare the non-public destructor,</li>
+<li>then declare all non-public member functions, and</li>
+<li>then declare all non-public member variables.</li>
+</ul>
+
+<p>
+Semantic constraints may require a different declaration order,
+but seek to minimize the potential confusion.
+</p>
+
+<p>
+Close a class definition
+with a right brace, semicolon, optional closing comment, and a new line.
+</p>
+
+<blockquote><pre><code>
+}; // class gnuclass
+</code></pre></blockquote>
+
+
+<h4><a name="Member_Form">Class Member Definitions</a></h4>
+
+<p>
+Define all members outside the class definition.
+That is, there are no function bodies or member initializers
+inside the class definition.
+</p>
+
+<p>
+Prefer to put the entire member head on a single line.
+</p>
+
+<blockquote><pre><code>
+gnuclass::gnuclass() : base_class()
+{
+  ...
+};
+</code></pre></blockquote>
+
+<p>
+When that is not possible,
+place the colon of the initializer clause at the beginning of a line.
+</p>
+
+<blockquote><pre><code>
+gnuclass::gnuclass()
+: base1(), base2(), member1(), member2(), member3(), member4()
+{
+  ...
+};
+</code></pre></blockquote>
+
+<p>
+If the initializer clause exceeds one line,
+move overflowing initializers to the next line and indent by two spaces.
+</p>
+
+<blockquote><pre><code>
+gnuclass::gnuclass()
+: base1(some_expression), base2(another_expression),
+  member1(my_expressions_everywhere)
+{
+  ...
+};
+</code></pre></blockquote>
+
+<p>
+If a C++ function name is long enough
+to cause the first function parameter with its type to exceed 80 characters,
+it should appear on the next line indented four spaces.
+</p>
+
+<blockquote><pre><code>
+void
+very_long_class_name::very_long_function_name(
+    very_long_type_name arg)
+{
+</code></pre></blockquote>
+
+<p>
+Sometimes the class qualifier and function name together exceed 80 characters.
+In this case, break the line before the <code>::</code> operator.
+We may wish to do so pre-emptively for all class member functions.
+</p>
+
+<blockquote><pre><code>
+void
+very_long_template_class_name &lt;with, a, great, many, arguments&gt;
+::very_long_function_name(
+    very_long_type_name arg)
+{
+</code></pre></blockquote>
+
+
+<h4><a name="Template_Form">Templates</a></h4>
+
+<p>
+A declaration following a template parameter list
+should not have additional indentation.
+</p>
+
+<p>
+Prefer <code>typename</code> over <code>class</code>
+in template parameter lists.
+</p>
+
+
+<h4><a name="ExternC">Extern "C"</a></h4>
+
+<p>
+Prefer an <code>extern "C"</code> block to a declaration qualifier.
+</p>
+
+<p>
+Open an <code>extern "C"</code> block with the left brace on the same line.
+</p>
+
+<blockquote><pre><code>
+extern "C" {
+</code></pre></blockquote>
+
+<p>
+Close an <code>extern "C"</code> block
+with a right brace, optional closing comment, and a new line.
+</p>
+
+<blockquote><pre><code>
+} // extern "C"
+</code></pre></blockquote>
+
+<p>
+Definitions within the body of a namespace are not indented.
+</p>
+
+<h4><a name="Namespace_Form">Namespaces</a></h4>
+
+<p>
+Open a namespace with the namespace name
+followed by a left brace and a new line.
+</p>
+
+<blockquote><pre><code>
+namespace gnutool {
+</code></pre></blockquote>
+
+<p>
+Close a namespace
+with a right brace, optional closing comment, and a new line.
+</p>
+
+<blockquote><pre><code>
+} // namespace gnutool
+</code></pre></blockquote>
+
+<p>
+Definitions within the body of a namespace are not indented.
+</p>
+
+
 </body>
 </html>
Index: htdocs/codingrationale.html
===================================================================
RCS file: htdocs/codingrationale.html
diff -N htdocs/codingrationale.html
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ htdocs/codingrationale.html	25 Jun 2012 22:19:46 -0000
@@ -0,0 +1,389 @@ 
+<head>
+<title>GCC Coding Conventions Rationale and Discussion</title>
+</head>
+
+<body>
+<h1>GCC Coding Conventions Rationale and Discussion</h1>
+
+<h2>C and C++ Language Conventions</h2>
+
+<h3>Language Use</h3>
+
+<h4>Inlining Functions</h4>
+
+<p>
+Inlining functions has a potential cost in object size,
+working set size, compile time, and debuggablity.
+These costs should not be borne without some evidence
+that the inlining pays for itself.
+</p>
+
+
+<h2>C++ Language Conventions</h2>
+
+<h3>Language Use</h3>
+
+<h4><a name="variables">Variable Definitions</a></h4>
+
+<p>
+Defining variables when they are first needed
+reduces the cognitive burden on the programmer.
+It also eases converting common sub-expressions
+into a defined and reused variable.
+</p>
+
+<p>
+Defining and testing variables in control expressions
+has the same advantages as above.
+In addition, it restricts the scope of the variable
+to the region in which it is known to be sensible.
+</p>
+
+<blockquote><pre><code>
+if (info *q = get_any_available_info ()) {
+  // q is known to be non-NULL, and so do useful processing.
+}
+</code></pre></blockquote>
+
+
+<h4><a name="struct">Struct Definitions</a></h4>
+
+<p>
+In the C++ standard,
+structs and classes differ only in the default access rules.
+We prefer to use these two keywords to signal more information.
+</p>
+
+<p>
+Note that under this definition,
+structs may have member functions.
+This freedom is useful for transitional code.
+</p>
+
+
+<h4><a name="class">Class Definitions</a></h4>
+
+<p>
+Forgetting to write a special member function is a known programming problem.
+Some authors recommend always defining all special member functions.
+Such classes are less efficient.
+First, these definitions may prevent the compiler
+from passing the class in a register.
+Second, these definitions may prevent the compiler
+from using more efficient methods for copying.
+Adding a comment that the default is intended
+preserves the performance while ensuring that
+the function was not forgotten.
+</p>
+
+<p>
+FIXME: Discussion of deleting inappropraite special members.
+Classes generally are either value classes or identity classes.
+Copy constructors and assignment operators are fine for value classes.
+They are often not appropriate to identity classes.
+These classes should delete, or disable, these functions.
+Marking such functions as follows
+will enable compiling against C++03,
+and later modifying them for C++11.
+</p>
+
+<blockquote><pre><code>
+TypeName(const TypeName&amp;) /*DELETED*/;
+void operator=(const TypeName&amp;) /*DELETED*/;
+</code></pre></blockquote>
+
+<p>
+Multiple inheritance is confusing and rarely useful.
+When it is needed though, there may be no substitute.
+Seek guidance, review and feedback from the wider community.
+</p>
+
+<p>
+Using virtual functions increases the size of instances of the class
+by at least one pointer.
+In heavily allocated types, such as trees, GIMPLE or RTL,
+this size increase could have adverse performance impacts.
+On the other hand,
+virtual functions can often reduce the size of instances
+by binding information into the virtual tables and the virtual functions.
+For example, various type tags need not be present.
+Other attributes can be inferred
+from type and more general information,
+or from extending the class hierarchy at the leaves.
+So, even though trees are heavily allocated,
+it remains to be seen whether virtual functions would increase the size.
+Virtual functions are implemented as indirect function calls,
+which can inhibit some optimization,
+particularly inlining.
+Therefore virtual functions should be added in heavily allocated classes
+only after size and performance studies.
+However, virtual functions are acceptable where we use hooks today,
+as they are already essentially virtual tables.
+</p>
+
+<p>
+There are good reasons to make private
+all data members of non-POD classes.
+However, in converting from C to C++,
+there is a necessary transition that has public data members.
+</p>
+
+
+<h4><a name="constructors">Constructors and Destructors</a></h4>
+
+<p>
+The compiler implicitly initializes all non-POD fields.
+Any initialization in the body of the constructor implies extra work.
+</p>
+
+<p>
+Polymorphic classes without a virtual destructor
+are almost certainly incorrect.
+</p>
+
+<h4><a name="conversions">Conversions</a></h4>
+
+<p>
+C++ uses single-argument constructors for implicit type conversion.
+Wide use of implicit conversion can cause some very surprising results.
+</p>
+
+<p>
+C++03 has no explicit conversion operators,
+and hence using them cannot avoid suprises.
+Wait for C++11.
+</p>
+
+
+<h4><a name="overfunc">Overloading Functions</a></h4>
+
+<p>
+Function overloading can be confusing.
+However, in some cases introducing new function names adds little value,
+as in the current distinction
+between <code>build_index_type</code> and <code>build_index_2_type</code>.
+</p>
+
+<p>
+The essential problem is to use overloading in a way that
+improves conciseness without introducing confusion.
+To that end, consider the following advice.
+</p>
+
+<p>
+You may overload if the overloaded name supports an action notion.
+For example, the C++ standard's notion of swap.
+</p>
+
+<p>
+You may <em>not</em> overload
+when implicit conversions among argument types may yield unintended effects.
+For example,
+</p>
+
+<blockquote><pre><code>
+void swizzle (int arg);
+void swizzle (const char *arg);
+... swizzle (NULL); ...
+</code></pre></blockquote>
+
+<p>
+results in an unintended call to the <code>int</code> overload on some systems.
+In practice, the problem that this restriction addresses
+arises more from bad user-defined implicit conversion operators.
+See ISO C++
+<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2437.pdf">
+N2437</a>
+and
+ISO C++
+<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2514.html">
+N2514</a>.
+</p>
+
+<p>
+You may overload if a single argument, in a single position,
+has multiple representations. For example,
+</p>
+
+<blockquote><pre><code>
+void append (const char *str);
+void append (std::string str);
+</code></pre></blockquote>
+
+<p>
+You may <em>not</em> overload
+if more than one argument constitutes the representation of some data notion.
+For example, in
+</p>
+
+<blockquote><pre><code>
+void register (int house, const char *street, int zipcode);
+</code></pre></blockquote>
+
+<p>
+the arguments are a representation of addresses.
+Instead, the overload should be on addresses.
+</p>
+
+<blockquote><pre><code>
+void register(const Address &amp;addr);
+</code></pre></blockquote>
+
+<p>
+This restriction cannot apply to constructors,
+where the whole point is to collect representational data.
+</p>
+
+<blockquote><pre><code>
+Address::Address (int house, const char *street, int zipcode);
+</code></pre></blockquote>
+
+<p>
+Notwithstanding the restrictions above, you may overload to detect errors.
+That is, if unsigned numbers are good, but signed numbers are bad,
+you could overload
+</p>
+
+<blockquote><pre><code>
+void munch (unsigned int arg);
+void munch (int arg);
+</code></pre></blockquote>
+
+<p>
+and simply not define the signed int version.
+Anyone using it would get a link-time error.
+(The C++11 standard has a syntax
+that enables compile-time detection of the problem.)
+</p>
+
+
+<h4><a name="overoper">Overloading Operators</a></h4>
+
+<p>
+Using <code>[]</code> to index a vector is unsurprising,
+but using <code>[]</code> to query a database over a network
+is bound to cause performance problems.
+</p>
+
+
+<h4><a name="default">Default Arguments</a></h4>
+
+<p>
+Expensive default arguments can cause hard-to-identify performance problems.
+</p>
+
+<p>
+Default arguments cause confusion
+when attempting to take the address of a function.
+They clause client code taking the address of a function
+to break when a default argument is replaced by a specialized overload.
+So, default arguments should generally not be used
+in customer-facing interfaces.
+Consider function overloading instead.
+</p>
+
+
+<h4><a name="namespace">Namespaces</a></h4>
+
+<p>
+Putting <code>using</code> directives
+or namespace-scope <code>using</code> declarations
+into header files can change client code in surprising ways.
+</p>
+
+<p>
+Using them within an implementation file can help conciseness.
+</p>
+
+
+<h4><a name="RTTI">RTTI and <code>dynamic_cast</code></a></h4>
+
+<p>
+Disabling RTTI will save space in the compiler.
+</p>
+
+<p>
+Checking the type of a class at runtime usually indicates a design problem.
+If you need classes to behave differently at runtime, use a virtual method.
+If you need to know the type of a class for some other reason,
+use an enum or a virtual member function
+that coverts a pointer to the more derived class.
+For example,
+</p>
+
+<blockquote><pre><code>
+common_type *p = ....;
+if (specific_type *q = p-&gt;to_specific ()) {
+  // We have and can use a specific_type pointed to by q.
+}
+</code></pre></blockquote>
+
+<h4><a name="casts">Other Casts</a></h4>
+
+<p>
+C++-style casts are very explicit in the intended transformation.
+Making intent clear avoids bugs and helps with other programmers.
+</p>
+
+
+<h4><a name="exceptions">Exceptions</a></h4>
+
+<p>
+The current compiler code is not exception safe.
+</p>
+
+<p>
+Disabling exceptions will permit
+the compiler itself to be slightly more optimized.
+</p>
+
+<p>
+Aborting the compiler is a reasonable response to unexpected problems.
+</p>
+
+<p>
+We would like the compiler to be exception safe,
+to permit reconsideration of the exception convention.
+This change would require a significant change in style,
+adopting "resource acquisition is initialization" (RAII).
+We would be using
+<code>shared_ptr</code> (from TR1's <code>&lt;memory&gt;</code>)
+or <code>unique_ptr</code> (from C++11).
+</p>
+
+<h4><a name="stdlib">The Standard Library</a></h4>
+
+<p>
+At present, C++ provides no great advantage for i18n.
+GCC does type checking for <code>printf</code> arguments,
+so the type insecurity of <code>printf</code> is moot,
+but the clarity in layout persists.
+For quick debugging output, &lt;iostream&gt; requires less work.
+</p>
+
+<h3>Formatting Conventions</h3>
+
+<h4><a href="names">Names</a></h4>
+
+<p>
+Naming data members with a trailing underscore
+highlights the extra overhead of access to fields over local variables.
+Think of the trailing underscore
+like you would Pascal's postfix <code>^</code> dereference operator.
+</p>
+
+<p>
+When using the above convention,
+the constructor parameter names
+and getter member function names
+can use the more concise non-underscore form.
+</p>
+
+</body>
+</html>

-- 
Lawrence Crowl