This is the mail archive of the
gcc-patches@gcc.gnu.org
mailing list for the GCC project.
Re: [wwwdocs] Update coding conventions for C++
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.
> > > + <a href="#C_Options">Compiler Options</a><br />
>
> I don't like this repeated 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