Re: [wwwdocs] Update coding conventions for C++
On 7/10/12, Gabriel Dos Reis g...@cs.tamu.edu wrote: Jason Merrill ja...@redhat.com writes: | On 07/09/2012 06:00 PM, Lawrence Crowl wrote: | Done. New patch attached, but note that the html tags have been | stripped from the patch to avoid mailer problems. | | Thanks. If nobody else has any comments, I think this is good to go. Great! Committed! -- Lawrence Crowl
Re: [wwwdocs] Update coding conventions for C++
Lawrence Crowl cr...@google.com writes: | On 7/10/12, Gabriel Dos Reis g...@cs.tamu.edu wrote: | Jason Merrill ja...@redhat.com writes: | | | On 07/09/2012 06:00 PM, Lawrence Crowl wrote: | | Done. New patch attached, but note that the html tags have been | | stripped from the patch to avoid mailer problems. | | | | Thanks. If nobody else has any comments, I think this is good to go. | | Great! | | Committed! Thanks! -- Gaby
Re: [wwwdocs] Update coding conventions for C++
On 07/09/2012 06:00 PM, Lawrence Crowl wrote: Done. New patch attached, but note that the html tags have been stripped from the patch to avoid mailer problems. Thanks. If nobody else has any comments, I think this is good to go. Jason
Re: [wwwdocs] Update coding conventions for C++
Jason Merrill ja...@redhat.com writes: | On 07/09/2012 06:00 PM, Lawrence Crowl wrote: | Done. New patch attached, but note that the html tags have been | stripped from the patch to avoid mailer problems. | | Thanks. If nobody else has any comments, I think this is good to go. Great! -- Gaby
Re: [wwwdocs] Update coding conventions for C++
On 7/4/12, Jason Merrill ja...@redhat.com wrote:
On 07/03/2012 04:37 PM, Lawrence Crowl wrote:
On 7/1/12, Jason Merrillja...@redhat.com wrote:
As discussed, I would say that RTTI is currently not permitted
but could be added later.
But isn't could be added later always true? Other folks have
objected to such wording on the grounds that it adds no information,
so I hesistate to add such wording now.
I suppose.
For the rationale, I would say that disabling RTTI saves some space
for classes with virtual functions when it isn't used, but could
be enabled if it would be useful in some part of the compiler.
And then remove the rest of the rationale.
I think you're objecting to Checking the type of a class at
runtime usually indicates a design problem. I copied this text
from the wiki. Does anyone object to me removing it?
I also object to the rest of the rationale. I would be OK with just
leaving Disabling RTTI will save space in the compiler and removing
the rest.
Done. New patch attached, but note that the html tags have been
stripped from the patch to avoid mailer problems.
--
Lawrence Crowl
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 - 1.66
+++ htdocs/codingconventions.html 9 Jul 2012 15:48:37 -
@@ -15,8 +19,73 @@
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
+lia href=#DocumentationDocumentation/a/li
+lia href=#ChangeLogsChangeLogs/a/li
+lia href=#PortabilityPortability/a/li
+lia href=#MakefilesMakefiles/a/li
+lia href=#TestsuiteTestsuite Conventions/a/li
+lia href=#DiagnosticsDiagnostics Conventions/a/li
+lia href=#SpellingSpelling, terminology and markup/a/li
+lia href=#CandCxxC and C++ Language Conventions/a
+ul
+lia href=#C_OptionsCompiler Options/a/li
+lia href=#C_LanguageLanguage Use/a
+ul
+lia href=#AssertionsAssertions/a/li
+lia href=#CharacterCharacter Testing/a/li
+lia href=#ErrorError Node Testing/a/li
+lia href=#GeneratedParameters Affecting Generated Code/a/li
+lia href=#C_InliningInlining Functions/a/li
+/ul
+/li
+lia href=#C_FormattingFormatting Conventions/a
+ul
+lia href=#LineLine Length/a/li
+lia href=#C_NamesNames/a/li
+lia href=#ExpressionsExpressions/a/li
+/ul
+/li
+/ul
+/li
+lia href=#Cxx_ConventionsC++ Language Conventions/a
+ul
+lia href=#Cxx_LanguageLanguage Use/a
+ul
+lia href=#VariableVariable Definitions/a/li
+lia href=#Struct_UseStruct Definitions/a/li
+lia href=#Class_UseClass Definitions/a/li
+lia href=#ConstructorsConstructors and Destructors/a/li
+lia href=#ConversionsConversions/a/li
+lia href=#Over_FuncOverloading Functions/a/li
+lia href=#Over_OperOverloading Operators/a/li
+lia href=#DefaultDefault Arguments/a/li
+lia href=#Cxx_InliningInlining Functions/a/li
+lia href=#Template_UseTemplates/a/li
+lia href=#Namespace_UseNamespaces/a/li
+lia href=#RTTIRTTI and codedynamic_cast/code/a/li
+lia href=#CastsOther Casts/a/li
+lia href=#ExceptionsExceptions/a/li
+lia href=#Standard_LibraryThe Standard Library/a/li
+/ul
+/li
+lia href=#Cxx_FormattingFormatting Conventions/a
+ul
+lia href=#Cxx_NamesNames/a/li
+lia href=#Struct_FormStruct Definitions/a/li
+lia href=#Class_FormClass Definitions/a/li
+lia href=#Member_FormClass Member Definitions/a/li
+lia href=#Template_FormTemplates/a/li
+lia href=#ExternCExtern C/a/li
+lia href=#Namespace_FormNamespaces/a/li
+/ul
+/li
+/ul
+/li
+/ul
-h2Documentation/h2
+
+h2a name=DocumentationDocumentation/a/h2
pDocumentation, both of user interfaces and of internals, must be
maintained and kept up to date. In particular:/p
@@ -43,7 +112,7 @@
/ul
-h2ChangeLogs/h2
+h2a name=ChangeLogsChangeLogs/a/h2
pGCC requires ChangeLog entries for documentation changes; for the web
pages (apart from codejava//code and codelibstdc++//code) the CVS
@@ -71,20 +140,40 @@
codejava/58/code is the actual number of the PR) at the top
of the ChangeLog entry./p
-h2Portability/h2
+h2a name=PortabilityPortability/a/h2
pThere 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
Re: [wwwdocs] Update coding conventions for C++
On 07/03/2012 04:37 PM, Lawrence Crowl wrote: On 7/1/12, Jason Merrillja...@redhat.com wrote: As discussed, I would say that RTTI is currently not permitted but could be added later. But isn't could be added later always true? Other folks have objected to such wording on the grounds that it adds no information, so I hesistate to add such wording now. I suppose. For the rationale, I would say that disabling RTTI saves some space for classes with virtual functions when it isn't used, but could be enabled if it would be useful in some part of the compiler. And then remove the rest of the rationale. I think you're objecting to Checking the type of a class at runtime usually indicates a design problem. I copied this text from the wiki. Does anyone object to me removing it? I also object to the rest of the rationale. I would be OK with just leaving Disabling RTTI will save space in the compiler and removing the rest. Jason
Re: [wwwdocs] Update coding conventions for C++
On 7/1/12, Gabriel Dos Reis g...@integrable-solutions.net wrote: On Fri, Jun 29, 2012 at 1:17 PM, Lawrence Crowl cr...@google.com wrote: Resend, as I replied to a message that didn't have the usual suspects on the cc line. On 6/27/12, Lawrence Crowl cr...@google.com wrote: ..., does anyone object to removing the permission to use C++ streams? Having heard no objection, I removed the permission. This is an area where I think we should not be too prescriptive. Clearly, the diagnostics machinery will be used for anything diagnostics -- so whether IOStreams are allowed or not would not change that. On the other hand, I feel we should defer to maintainers' discretion in specific areas whether people are implementing dumping or other I/O facilities not related to diagnostics, since as I you correctly pointed out, there is an added value of flexibility and expressivity. In summary: Instead of blanket ban, I would suggest that uses for C++ I/O streams be reserved for non-diagnostics purposes and left at the discretion of maintainers. Given that maintainers have discretion to grant exceptions anyway, would you be willing to let the wording stand without that permission? I'd like to get the document committed in some form so that we can make progress on the dependent activities. At present, none of those activities depend on this issue. -- Lawrence Crowl
Re: [wwwdocs] Update coding conventions for C++
On 7/1/12, Jason Merrill ja...@redhat.com wrote: On 06/29/2012 02:17 PM, Lawrence Crowl wrote: +h4a name=RTTIRTTI andcodedynamic_cast/code/a/h4 + +p +Run-time type information (RTTI) is permitted +when certain non-defaultcode--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 withcode-fno-rtti/code. +/p As discussed, I would say that RTTI is currently not permitted but could be added later. But isn't could be added later always true? Other folks have objected to such wording on the grounds that it adds no information, so I hesistate to add such wording now. For the rationale, I would say that disabling RTTI saves some space for classes with virtual functions when it isn't used, but could be enabled if it would be useful in some part of the compiler. And then remove the rest of the rationale. I think you're objecting to Checking the type of a class at runtime usually indicates a design problem. I copied this text from the wiki. Does anyone object to me removing it? I'd like to get the document committed in some form so that we can make progress on the dependent activities. At present, none of those activities depend on this issue. -- Lawrence Crowl
Re: [wwwdocs] Update coding conventions for C++
Lawrence Crowl cr...@google.com writes: | On 7/1/12, Gabriel Dos Reis g...@integrable-solutions.net wrote: | On Fri, Jun 29, 2012 at 1:17 PM, Lawrence Crowl cr...@google.com wrote: | Resend, as I replied to a message that didn't have the usual suspects | on the cc line. | | On 6/27/12, Lawrence Crowl cr...@google.com wrote: | ..., does anyone object to removing the permission to use C++ | streams? | | Having heard no objection, I removed the permission. | | This is an area where I think we should not be too prescriptive. | Clearly, the diagnostics machinery will be used for anything | diagnostics -- so whether IOStreams are allowed or not would | not change that. On the other hand, I feel we should defer to | maintainers' discretion in specific areas whether people are | implementing dumping or other I/O facilities not related to | diagnostics, since as I you correctly pointed out, there is an | added value of flexibility and expressivity. | | In summary: Instead of blanket ban, I would suggest that uses for | C++ I/O streams be reserved for non-diagnostics purposes and left | at the discretion of maintainers. | | Given that maintainers have discretion to grant exceptions | anyway, would you be willing to let the wording stand without | that permission? My concern is that this might be construed later in forms that weren't intented, which is why I have been reluctant about prescriptive guidelines. | | I'd like to get the document committed in some form so that we can | make progress on the dependent activities. At present, none of | those activities depend on this issue. Agreed. -- Gaby
Re: [wwwdocs] Update coding conventions for C++
On Fri, Jun 29, 2012 at 1:17 PM, Lawrence Crowl cr...@google.com wrote: Resend, as I replied to a message that didn't have the usual suspects on the cc line. On 6/27/12, Lawrence Crowl cr...@google.com wrote: ..., does anyone object to removing the permission to use C++ streams? Having heard no objection, I removed the permission. This is an area where I think we should not be too prescriptive. Clearly, the diagnostics machinery will be used for anything diagnostics -- so whether IOStreams are allowed or not would not change that. On the other hand, I feel we should defer to maintainers' discretion in specific areas whether people are implementing dumping or other I/O facilities not related to diagnostics, since as I you correctly pointed out, there is an added value of flexiibility and expressivity. In summary: Instead of blanket ban, I would suggest that uses for C++ I/O streams be reserved for non-diagnostics purposes and left at the discretion of maintainers. The following patch is the current state of the changes. Since the discussion appears to have died down, can I commit this patch?
Re: [wwwdocs] Update coding conventions for C++
On 06/29/2012 02:17 PM, Lawrence Crowl wrote: +h4a name=RTTIRTTI andcodedynamic_cast/code/a/h4 + +p +Run-time type information (RTTI) is permitted +when certain non-defaultcode--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 withcode-fno-rtti/code. +/p As discussed, I would say that RTTI is currently not permitted but could be added later. For the rationale, I would say that disabling RTTI saves some space for classes with virtual functions when it isn't used, but could be enabled if it would be useful in some part of the compiler. And then remove the rest of the rationale. Jason
Re: [wwwdocs] Update coding conventions for C++
Resend, as I replied to a message that didn't have the usual suspects
on the cc line.
On 6/27/12, Lawrence Crowl cr...@google.com wrote:
..., does anyone object to removing the permission to use C++
streams?
Having heard no objection, I removed the permission.
The following patch is the current state of the changes. Since the
discussion appears to have died down, can I commit this patch?
BTW, as before, I have removed the html tags from this patch,
as they cause the mail server to reject the 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 - 1.66
+++ htdocs/codingconventions.html 28 Jun 2012 22:03:38 -
@@ -15,8 +19,73 @@
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
+lia href=#DocumentationDocumentation/a/li
+lia href=#ChangeLogsChangeLogs/a/li
+lia href=#PortabilityPortability/a/li
+lia href=#MakefilesMakefiles/a/li
+lia href=#TestsuiteTestsuite Conventions/a/li
+lia href=#DiagnosticsDiagnostics Conventions/a/li
+lia href=#SpellingSpelling, terminology and markup/a/li
+lia href=#CandCxxC and C++ Language Conventions/a
+ul
+lia href=#C_OptionsCompiler Options/a/li
+lia href=#C_LanguageLanguage Use/a
+ul
+lia href=#AssertionsAssertions/a/li
+lia href=#CharacterCharacter Testing/a/li
+lia href=#ErrorError Node Testing/a/li
+lia href=#GeneratedParameters Affecting Generated
Code/a/li
+lia href=#C_InliningInlining Functions/a/li
+/ul
+/li
+lia href=#C_FormattingFormatting Conventions/a
+ul
+lia href=#LineLine Length/a/li
+lia href=#C_NamesNames/a/li
+lia href=#ExpressionsExpressions/a/li
+/ul
+/li
+/ul
+/li
+lia href=#Cxx_ConventionsC++ Language Conventions/a
+ul
+lia href=#Cxx_LanguageLanguage Use/a
+ul
+lia href=#VariableVariable Definitions/a/li
+lia href=#Struct_UseStruct Definitions/a/li
+lia href=#Class_UseClass Definitions/a/li
+lia href=#ConstructorsConstructors and Destructors/a/li
+lia href=#ConversionsConversions/a/li
+lia href=#Over_FuncOverloading Functions/a/li
+lia href=#Over_OperOverloading Operators/a/li
+lia href=#DefaultDefault Arguments/a/li
+lia href=#Cxx_InliningInlining Functions/a/li
+lia href=#Template_UseTemplates/a/li
+lia href=#Namespace_UseNamespaces/a/li
+lia href=#RTTIRTTI and codedynamic_cast/code/a/li
+lia href=#CastsOther Casts/a/li
+lia href=#ExceptionsExceptions/a/li
+lia href=#Standard_LibraryThe Standard Library/a/li
+/ul
+/li
+lia href=#Cxx_FormattingFormatting Conventions/a
+ul
+lia href=#Cxx_NamesNames/a/li
+lia href=#Struct_FormStruct Definitions/a/li
+lia href=#Class_FormClass Definitions/a/li
+lia href=#Member_FormClass Member Definitions/a/li
+lia href=#Template_FormTemplates/a/li
+lia href=#ExternCExtern C/a/li
+lia href=#Namespace_FormNamespaces/a/li
+/ul
+/li
+/ul
+/li
+/ul
-h2Documentation/h2
+
+h2a name=DocumentationDocumentation/a/h2
pDocumentation, both of user interfaces and of internals, must be
maintained and kept up to date. In particular:/p
@@ -43,7 +112,7 @@
/ul
-h2ChangeLogs/h2
+h2a name=ChangeLogsChangeLogs/a/h2
pGCC requires ChangeLog entries for documentation changes; for the web
pages (apart from codejava//code and codelibstdc++//code) the CVS
@@ -71,20 +140,40 @@
codejava/58/code is the actual number of the PR) at the top
of the ChangeLog entry./p
-h2Portability/h2
+h2a name=PortabilityPortability/a/h2
pThere 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
+codegcc/code, codelibcpp/code and codefixincludes/code
+may use C++03.
+They may also use the codelong 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 emshould/em also be
Re: [wwwdocs] Update coding conventions for C++
On Wed, 27 Jun 2012, Lawrence Crowl wrote: +h4a name=Namespace_UseNamespaces/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 Do all people have a consensus on the use of namespace ? Well, we really only know about objections, and I have not seen any. I certainly think namespaces are a useful feature to use in GCC (with a namespace for the gcc/ directory, or as you imply separate ones for the driver and the compilers proper, one for libcpp, one for each front end, etc.). -- Joseph S. Myers jos...@codesourcery.com
Re: [wwwdocs] Update coding conventions for C++
On 6/27/12, Lawrence Crowl cr...@google.com wrote:
..., does anyone object to removing the permission to use C++
streams?
Having heard no objection, I removed the permission.
The following patch is the current state of the changes. Since the
discussion appears to have died down, can I commit this patch?
BTW, as before, I have removed the html tags from this patch,
as they cause the mail server to reject the 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 - 1.66
+++ htdocs/codingconventions.html 28 Jun 2012 22:03:38 -
@@ -15,8 +19,73 @@
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
+lia href=#DocumentationDocumentation/a/li
+lia href=#ChangeLogsChangeLogs/a/li
+lia href=#PortabilityPortability/a/li
+lia href=#MakefilesMakefiles/a/li
+lia href=#TestsuiteTestsuite Conventions/a/li
+lia href=#DiagnosticsDiagnostics Conventions/a/li
+lia href=#SpellingSpelling, terminology and markup/a/li
+lia href=#CandCxxC and C++ Language Conventions/a
+ul
+lia href=#C_OptionsCompiler Options/a/li
+lia href=#C_LanguageLanguage Use/a
+ul
+lia href=#AssertionsAssertions/a/li
+lia href=#CharacterCharacter Testing/a/li
+lia href=#ErrorError Node Testing/a/li
+lia href=#GeneratedParameters Affecting Generated Code/a/li
+lia href=#C_InliningInlining Functions/a/li
+/ul
+/li
+lia href=#C_FormattingFormatting Conventions/a
+ul
+lia href=#LineLine Length/a/li
+lia href=#C_NamesNames/a/li
+lia href=#ExpressionsExpressions/a/li
+/ul
+/li
+/ul
+/li
+lia href=#Cxx_ConventionsC++ Language Conventions/a
+ul
+lia href=#Cxx_LanguageLanguage Use/a
+ul
+lia href=#VariableVariable Definitions/a/li
+lia href=#Struct_UseStruct Definitions/a/li
+lia href=#Class_UseClass Definitions/a/li
+lia href=#ConstructorsConstructors and Destructors/a/li
+lia href=#ConversionsConversions/a/li
+lia href=#Over_FuncOverloading Functions/a/li
+lia href=#Over_OperOverloading Operators/a/li
+lia href=#DefaultDefault Arguments/a/li
+lia href=#Cxx_InliningInlining Functions/a/li
+lia href=#Template_UseTemplates/a/li
+lia href=#Namespace_UseNamespaces/a/li
+lia href=#RTTIRTTI and codedynamic_cast/code/a/li
+lia href=#CastsOther Casts/a/li
+lia href=#ExceptionsExceptions/a/li
+lia href=#Standard_LibraryThe Standard Library/a/li
+/ul
+/li
+lia href=#Cxx_FormattingFormatting Conventions/a
+ul
+lia href=#Cxx_NamesNames/a/li
+lia href=#Struct_FormStruct Definitions/a/li
+lia href=#Class_FormClass Definitions/a/li
+lia href=#Member_FormClass Member Definitions/a/li
+lia href=#Template_FormTemplates/a/li
+lia href=#ExternCExtern C/a/li
+lia href=#Namespace_FormNamespaces/a/li
+/ul
+/li
+/ul
+/li
+/ul
-h2Documentation/h2
+
+h2a name=DocumentationDocumentation/a/h2
pDocumentation, both of user interfaces and of internals, must be
maintained and kept up to date. In particular:/p
@@ -43,7 +112,7 @@
/ul
-h2ChangeLogs/h2
+h2a name=ChangeLogsChangeLogs/a/h2
pGCC requires ChangeLog entries for documentation changes; for the web
pages (apart from codejava//code and codelibstdc++//code) the CVS
@@ -71,20 +140,40 @@
codejava/58/code is the actual number of the PR) at the top
of the ChangeLog entry./p
-h2Portability/h2
+h2a name=PortabilityPortability/a/h2
pThere 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
+codegcc/code, codelibcpp/code and codefixincludes/code
+may use C++03.
+They may also use the codelong 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 emshould/em also be compatible with C++11.
+/p
+
+p
+The directories libiberty and libdecnumber must use C
+and
Re: [wwwdocs] Update coding conventions for C++
On Wed, Jun 27, 2012 at 2:35 AM, Magnus Fromreide ma...@lysator.liu.se wrote: On Mon, 2012-06-25 at 15:17 -0700, Lawrence Crowl wrote: On 6/25/12, Joseph S. Myers jos...@codesourcery.com wrote: On Mon, 25 Jun 2012, Diego Novillo wrote: [ Added doc maintainers in CC ] 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. Two spaces for members is common practice with GNU, and it seems to be used for libstdc++. One space for protection labels is not something I have heard of before and libstdc++ uses no indentation for them. A freshly started emacs also doesn't indent access labels. I do think there is some value in using the same coding style for libstdc++ and the compiler. I agree here. It's the same we do for case labels. Richard. /MF
Re: [wwwdocs] Update coding conventions for C++
[...] | Two spaces for members is common practice with GNU, and it seems to be | used for libstdc++. | | One space for protection labels is not something I have heard of before | and libstdc++ uses no indentation for them. | | A freshly started emacs also doesn't indent access labels. | | I do think there is some value in using the same coding style for | libstdc++ and the compiler. | | I agree here. It's the same we do for case labels. | | Richard. I think we reached total agreement :-) -- Gaby
Re: [wwwdocs] Update coding conventions for C++
On Wed, Jun 27, 2012 at 2:19 AM, Lawrence Crowl cr...@google.com wrote:
On 6/26/12, Jason Merrill ja...@redhat.com wrote:
On 06/25/2012 06:26 PM, Lawrence Crowl wrote:
+orcodegcc_unreachable/code. If the checks are expensive or the
+compiler can reasonably carry on after the error, they may be
+conditioned oncode--enable-checking/code./p
by using codegcc_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
+
+blockquoteprecode
+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 ?
--
Chiheng Xu
Re: [wwwdocs] Update coding conventions for C++
On Wed, Jun 27, 2012 at 2:35 PM, Chiheng Xu chiheng...@gmail.com wrote:
On Wed, Jun 27, 2012 at 2:19 AM, Lawrence Crowl cr...@google.com wrote:
On 6/26/12, Jason Merrill ja...@redhat.com wrote:
On 06/25/2012 06:26 PM, Lawrence Crowl wrote:
+orcodegcc_unreachable/code. If the checks are expensive or the
+compiler can reasonably carry on after the error, they may be
+conditioned oncode--enable-checking/code./p
by using codegcc_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
+
+blockquoteprecode
+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.
Re: [wwwdocs] Update coding conventions for C++
On Tue, Jun 19, 2012 at 6:28 AM, Lawrence Crowl cr...@google.com wrote: pFunction 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 +208,13 @@ necessary, to break mutually recursive cycles./p If you always put entry functions in the bottom of a source file, and generically, always put upper layer functions below the lower layer functions. Then probably there will be no need for function prototypes in a source file. +h4a name=Namespace_UseNamespaces/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 Do all people have a consensus on the use of namespace ? + +p +Header files should have neither codeusing/code directives +nor namespace-scope codeusing/code declarations. +/p + +p +There is no alternative to codeusing/code declarations +in class definitions to manage names within an inheritance hierarchy, +so they are necessarily permitted. +/p +h4a name=ExceptionsExceptions/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#exceptionsRationale and Discussion/a +/p + + +h4a name=Standard_LibraryThe 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 codeprintf/code style I/O +rather than codelt;iostreamgt;/code style I/O. +For quick debugging code, +codelt;iostreamgt;/code is permitted. +/p Is iostream really suitable or necessary for GCC ? Have you think about writing another thinner interface , like Java's IO stream. -- Chiheng Xu
Re: [wwwdocs] Update coding conventions for C++
Hi, On Tue, Jun 26, 2012 at 11:06:15AM -0700, Lawrence Crowl wrote: On 6/26/12, Martin Jambor mjam...@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 codeprintf/code style I/O +rather than codelt;iostreamgt;/code style I/O. +For quick debugging code, +codelt;iostreamgt;/code is permitted. +/p Similarly here, no quick and dirty debugging output should ever be committed, we should not +h4a name=stdlibThe Standard Library/a/h4 + +p +At present, C++ provides no great advantage for i18n. +GCC does type checking for codeprintf/code arguments, +so the type insecurity of codeprintf/code is moot, +but the clarity in layout persists. +For quick debugging output, lt;iostreamgt; 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
Re: [wwwdocs] Update coding conventions for C++
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
Re: [wwwdocs] Update coding conventions for C++
On 6/27/12, Martin Jambor mjam...@suse.cz wrote: On Tue, Jun 26, 2012 at 11:06:15AM -0700, Lawrence Crowl wrote: On 6/26/12, Martin Jambor mjam...@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 codeprintf/code style I/O +rather than codelt;iostreamgt;/code style I/O. +For quick debugging code, +codelt;iostreamgt;/code is permitted. +/p Similarly here, no quick and dirty debugging output should ever be committed, we should not +h4a name=stdlibThe Standard Library/a/h4 + +p +At present, C++ provides no great advantage for i18n. +GCC does type checking for codeprintf/code arguments, +so the type insecurity of codeprintf/code is moot, +but the clarity in layout persists. +For quick debugging output, lt;iostreamgt; 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? -- Lawrence Crowl
Re: [wwwdocs] Update coding conventions for C++
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: -h2Miscellaneous Conventions/h2 - -pCode should use codegcc_assert(EXPR)/code to check invariants. -Use codegcc_unreachable()/code to mark places that should never be -reachable (such as an unreachable codedefault/code case of a -switch). Do not use codegcc_assert(0)/code for such purposes, as -codegcc_unreachable/code gives the compiler more information. The -assertions are enabled unless explicitly configured off with -code--enable-checking=none/code. Do not use codeabort/code. -User input should never be validated by either codegcc_assert/code -or codegcc_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 codeprintf/code style I/O +rather than codelt;iostreamgt;/code style I/O. +For quick debugging code, +codelt;iostreamgt;/code is permitted. +/p Similarly here, no quick and dirty debugging output should ever be committed, we should not +h4a name=stdlibThe Standard Library/a/h4 + +p +At present, C++ provides no great advantage for i18n. +GCC does type checking for codeprintf/code arguments, +so the type insecurity of codeprintf/code is moot, +but the clarity in layout persists. +For quick debugging output, lt;iostreamgt; requires less work. +/p The same applies here. Thanks, Martin + +h3Formatting Conventions/h3 + +h4a href=namesNames/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
Re: [wwwdocs] Update coding conventions for C++
On 06/25/2012 06:26 PM, Lawrence Crowl wrote:
+orcodegcc_unreachable/code. If the checks are expensive or the
+compiler can reasonably carry on after the error, they may be
+conditioned oncode--enable-checking/code./p
by using codegcc_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
+
+blockquoteprecode
+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
Re: [wwwdocs] Update coding conventions for C++
On 6/25/12, Alexandre Oliva aol...@redhat.com wrote: On Jun 25, 2012, Lawrence Crowl cr...@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
Re: [wwwdocs] Update coding conventions for C++
On 6/26/12, Martin Jambor mjam...@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. -h2Miscellaneous Conventions/h2 - -pCode should use codegcc_assert(EXPR)/code to check invariants. -Use codegcc_unreachable()/code to mark places that should never be -reachable (such as an unreachable codedefault/code case of a -switch). Do not use codegcc_assert(0)/code for such purposes, as -codegcc_unreachable/code gives the compiler more information. The -assertions are enabled unless explicitly configured off with -code--enable-checking=none/code. Do not use codeabort/code. -User input should never be validated by either codegcc_assert/code -or codegcc_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 codeprintf/code style I/O +rather than codelt;iostreamgt;/code style I/O. +For quick debugging code, +codelt;iostreamgt;/code is permitted. +/p Similarly here, no quick and dirty debugging output should ever be committed, we should not +h4a name=stdlibThe Standard Library/a/h4 + +p +At present, C++ provides no great advantage for i18n. +GCC does type checking for codeprintf/code arguments, +so the type insecurity of codeprintf/code is moot, +but the clarity in layout persists. +For quick debugging output, lt;iostreamgt; 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
Re: [wwwdocs] Update coding conventions for C++
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
Re: [wwwdocs] Update coding conventions for C++
On 6/26/12, Jason Merrill ja...@redhat.com wrote:
On 06/25/2012 06:26 PM, Lawrence Crowl wrote:
+orcodegcc_unreachable/code. If the checks are expensive or the
+compiler can reasonably carry on after the error, they may be
+conditioned oncode--enable-checking/code./p
by using codegcc_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
+
+blockquoteprecode
+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?
--
Lawrence Crowl
Re: [wwwdocs] Update coding conventions for C++
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. -- Joseph S. Myers jos...@codesourcery.com
Re: [wwwdocs] Update coding conventions for C++
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
Re: [wwwdocs] Update coding conventions for C++
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...
Re: [wwwdocs] Update coding conventions for C++
On Mon, 2012-06-25 at 15:17 -0700, Lawrence Crowl wrote: On 6/25/12, Joseph S. Myers jos...@codesourcery.com wrote: On Mon, 25 Jun 2012, Diego Novillo wrote: [ Added doc maintainers in CC ] 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. Two spaces for members is common practice with GNU, and it seems to be used for libstdc++. One space for protection labels is not something I have heard of before and libstdc++ uses no indentation for them. A freshly started emacs also doesn't indent access labels. I do think there is some value in using the same coding style for libstdc++ and the compiler. /MF
Re: [wwwdocs] Update coding conventions for C++
Magnus Fromreide ma...@lysator.liu.se writes: Two spaces for members is common practice with GNU, and it seems to be used for libstdc++. One space for protection labels is not something I have heard of before and libstdc++ uses no indentation for them. A freshly started emacs also doesn't indent access labels. Yeah, zero indentation (or rather, aligned with the surrounding brace level, e.g. for nested structures/classes) is certainly the defacto GNU standard for C++ access labels (private:, etc). There seems no reason for GCC to be different. -miles -- Quotation, n. The act of repeating erroneously the words of another. The words erroneously repeated.
Re: [wwwdocs] Update coding conventions for C++
[ 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? It has been a week since the conventions were posted and I have seen no comments on the patch. Thanks. Diego. On Mon, Jun 18, 2012 at 6:28 PM, Lawrence Crowl cr...@google.com wrote: This patch updates the coding conventions to C++. The primary source file is codingconventions.html. The coding conventions now refer to a new file, codingrationale.html, providing the rationale for some of the C++ conventions. The two files in question are attached whole for your convenience. The Portability section has some changes. The Miscellaneous Conventions section moves later and become part of the C and C++ Language Conventions section. The bulk of the change consists of additions to the C and C++ Language Conventions section and the addition of an entirely new C++ Language Conventions section. I added a table of contents. I have removed lines from the around the html tag, as they are causing my mail to be rejected. If you get this message twice, you now know why. :-) Please review. Index: codingconventions.html === RCS file: /cvs/gcc/wwwdocs/htdocs/codingconventions.html,v retrieving revision 1.66 diff -u -u -r1.66 codingconventions.html --- codingconventions.html 19 Feb 2012 00:45:34 - 1.66 +++ codingconventions.html 18 Jun 2012 22:04:49 - @@ -1,4 +1,8 @@ head titleGCC Coding Conventions/title @@ -15,8 +19,56 @@ code to follow these conventions, it is best to send changes to follow the conventions separately from any other changes to the code./p +p +a href=#DocumentationDocumentation/abr / +a href=#ChangeLogsChangeLogs/abr / +a href=#PortabilityPortability/abr / +a href=#MakefilesMakefiles/abr / +a href=#TestsuiteTestsuite Conventions/abr / +a href=#DiagnosticsDiagnostics Conventions/abr / +a href=#SpellingSpelling, terminology and markup/abr / +a href=#CandCxxC and C++ Language Conventions/abr / +nbsp;nbsp;nbsp;nbsp;a href=#C_OptionsCompiler Options/abr / +nbsp;nbsp;nbsp;nbsp;a href=#C_LanguageLanguage Use/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#AssertionsAssertions/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#CharacterCharacter Testing/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#ErrorError Node Testing/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#GeneratedParameters Affecting Generated Code/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#C_InliningInlining Functions/abr / +nbsp;nbsp;nbsp;nbsp;a href=#C_FormattingFormatting Conventions/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#LineLine Length/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#C_NamesNames/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#ExpressionsExpressions/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#CallsFunction Calls/abr / +a href=#Cxx_ConventionsC++ Language Conventions/abr / +nbsp;nbsp;nbsp;nbsp;a href=#Cxx_LanguageLanguage Use/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#VariableVariable Definitions/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#Struct_UseStruct Definitions/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#Class_UseClass Definitions/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#ConstructorsConstructors and Destructors/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#ConversionsConversions/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#Over_FuncOverloading Functions/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#Over_OperOverloading Operators/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#DefaultDefault Arguments/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#Cxx_InliningInlining Functions/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#Template_UseTemplates/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#Namespace_UseNamespaces/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#RTTIRTTI and codedynamic_cast/code/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#CastsOther Casts/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#ExceptionsExceptions/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#Standard_LibraryThe Standard Library/abr / +nbsp;nbsp;nbsp;nbsp;a href=#Cxx_FormattingFormatting Conventions/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#Cxx_NamesNames/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#Struct_FormStruct Definitions/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#Class_FormClass Definitions/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#Member_FormClass Member Definitions/abr /
Re: [wwwdocs] Update coding conventions for C++
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. +nbsp;nbsp;nbsp;nbsp;a href=#C_OptionsCompiler Options/abr / I don't like this repeated nbsp; presentational markup; use appropriate logical markup instead. +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. +h4a name=AssertionsAssertions/a/h4 + +pCode should use codegcc_assert(EXPR)/code to check invariants. +Use codegcc_unreachable()/code to mark places that should never be +reachable (such as an unreachable codedefault/code case of a +switch). Do not use codegcc_assert(0)/code for such purposes, as +codegcc_unreachable/code gives the compiler more information. The +assertions are enabled unless explicitly configured off with +code--enable-checking=none/code. Do not use codeabort/code. +User input should never be validated by either codegcc_assert/code +or codegcc_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? +h4a name=CallsFunction 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. +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. +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. -- Joseph S. Myers jos...@codesourcery.com
Re: [wwwdocs] Update coding conventions for C++
On 6/25/12, Joseph S. Myers jos...@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_OptionsCompiler Options/abr / 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. +h4a name=AssertionsAssertions/a/h4 + +pCode should use codegcc_assert(EXPR)/code to check invariants. +Use codegcc_unreachable()/code to mark places that should never be +reachable (such as an unreachable codedefault/code case of a +switch). Do not use codegcc_assert(0)/code for such purposes, as +codegcc_unreachable/code gives the compiler more information. The +assertions are enabled unless explicitly configured off with +code--enable-checking=none/code. Do not use codeabort/code. +User input should never be validated by either codegcc_assert/code +or codegcc_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. +h4a name=CallsFunction 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
Re: [wwwdocs] Update coding conventions for C++
On 6/25/12, Lawrence Crowl cr...@google.com wrote: On 6/25/12, Joseph S. Myers jos...@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_OptionsCompiler Options/abr / 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. +h4a name=AssertionsAssertions/a/h4 + +pCode should use codegcc_assert(EXPR)/code to check invariants. +Use codegcc_unreachable()/code to mark places that should never be +reachable (such as an unreachable codedefault/code case of a +switch). Do not use codegcc_assert(0)/code for such purposes, as +codegcc_unreachable/code gives the compiler more information. The +assertions are enabled unless explicitly configured off with +code--enable-checking=none/code. Do not use codeabort/code. +User input should never be validated by either codegcc_assert/code +or codegcc_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. +h4a name=CallsFunction 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. 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 - 1.66 +++ htdocs/codingconventions.html 25 Jun 2012 22:19:46 - @@ -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 +lia href=#DocumentationDocumentation/a/li +lia href=#ChangeLogsChangeLogs/a/li +lia href=#PortabilityPortability/a/li +lia
Re: [wwwdocs] Update coding conventions for C++
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
Re: [wwwdocs] Update coding conventions for C++
On 6/25/12, Benjamin Kosnik b...@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
Re: [wwwdocs] Update coding conventions for C++
On Jun 25, 2012, Lawrence Crowl cr...@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/ -- Alexandre Oliva, freedom fighterhttp://FSFLA.org/~lxoliva/ You must be the change you wish to see in the world. -- Gandhi Be Free! -- http://FSFLA.org/ FSF Latin America board member Free Software Evangelist Red Hat Brazil Compiler Engineer
Re: [wwwdocs] Update coding conventions for C++
This patch updates the coding conventions to C++. The primary source file is codingconventions.html. The coding conventions now refer to a new file, codingrationale.html, providing the rationale for some of the C++ conventions. The two files in question are attached whole for your convenience. The Portability section has some changes. The Miscellaneous Conventions section moves later and become part of the C and C++ Language Conventions section. The bulk of the change consists of additions to the C and C++ Language Conventions section and the addition of an entirely new C++ Language Conventions section. I added a table of contents. I have removed lines from the around the html tag, as they are causing my mail to be rejected. If you get this message twice, you now know why. :-) Please review. Index: codingconventions.html === RCS file: /cvs/gcc/wwwdocs/htdocs/codingconventions.html,v retrieving revision 1.66 diff -u -u -r1.66 codingconventions.html --- codingconventions.html 19 Feb 2012 00:45:34 - 1.66 +++ codingconventions.html 18 Jun 2012 22:04:49 - @@ -1,4 +1,8 @@ head titleGCC Coding Conventions/title @@ -15,8 +19,56 @@ code to follow these conventions, it is best to send changes to follow the conventions separately from any other changes to the code./p +p +a href=#DocumentationDocumentation/abr / +a href=#ChangeLogsChangeLogs/abr / +a href=#PortabilityPortability/abr / +a href=#MakefilesMakefiles/abr / +a href=#TestsuiteTestsuite Conventions/abr / +a href=#DiagnosticsDiagnostics Conventions/abr / +a href=#SpellingSpelling, terminology and markup/abr / +a href=#CandCxxC and C++ Language Conventions/abr / +nbsp;nbsp;nbsp;nbsp;a href=#C_OptionsCompiler Options/abr / +nbsp;nbsp;nbsp;nbsp;a href=#C_LanguageLanguage Use/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#AssertionsAssertions/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#CharacterCharacter Testing/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#ErrorError Node Testing/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#GeneratedParameters Affecting Generated Code/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#C_InliningInlining Functions/abr / +nbsp;nbsp;nbsp;nbsp;a href=#C_FormattingFormatting Conventions/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#LineLine Length/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#C_NamesNames/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#ExpressionsExpressions/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#CallsFunction Calls/abr / +a href=#Cxx_ConventionsC++ Language Conventions/abr / +nbsp;nbsp;nbsp;nbsp;a href=#Cxx_LanguageLanguage Use/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#VariableVariable Definitions/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#Struct_UseStruct Definitions/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#Class_UseClass Definitions/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#ConstructorsConstructors and Destructors/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#ConversionsConversions/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#Over_FuncOverloading Functions/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#Over_OperOverloading Operators/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#DefaultDefault Arguments/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#Cxx_InliningInlining Functions/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#Template_UseTemplates/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#Namespace_UseNamespaces/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#RTTIRTTI and codedynamic_cast/code/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#CastsOther Casts/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#ExceptionsExceptions/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#Standard_LibraryThe Standard Library/abr / +nbsp;nbsp;nbsp;nbsp;a href=#Cxx_FormattingFormatting Conventions/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#Cxx_NamesNames/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#Struct_FormStruct Definitions/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#Class_FormClass Definitions/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#Member_FormClass Member Definitions/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#Template_FormTemplates/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#ExternCExtern C/abr / +nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;nbsp;a href=#Namespace_FormNamespaces/abr / +/p -h2Documentation/h2 + +h2a name=DocumentationDocumentation/a/h2 pDocumentation, both of user interfaces and of internals, must be maintained and kept up to date. In particular:/p @@ -43,7 +95,7 @@ /ul -h2ChangeLogs/h2 +h2a name=ChangeLogsChangeLogs/a/h2 pGCC requires ChangeLog entries for documentation changes; for the web pages (apart from
