C++ Guidelines

[Pete Vidler]

Hi Folks,

I'm wondering if there is a compilation of C++ guidelines out there
anywhere. Here are some of the ones I've picked up so far (as examples):

- Functions should fit on one screen, from various sources.

- Non-leaf classes should be abstract (have pure virtual methods), from
More Effective C++, Item 33.

- Virtual methods should be private by default and protected if they
need access to a base classes version (except for the destructor, of
course), from http://www.gotw.ca/publications/mill18.htm.

- Header files should be self contained, from various sources.

- Destructors for base classes should be either virtual or protected.

I think I've probably missed (or never heard of) quite a few more.
Anyone know where I can find such things? Or have some guidelines of
their own to share?

-- Pete

[Daniel T.]

Re: C++ Guidelines

Pete Vidler <pvidler@mailbl ocks.com> wrote:
[color=blue]
> I'm wondering if there is a compilation of C++ guidelines out there
> anywhere. Here are some of the ones I've picked up so far (as examples):
>
> - Functions should fit on one screen, from various sources.
>
> - Non-leaf classes should be abstract (have pure virtual methods), from
> More Effective C++, Item 33.
>
> - Virtual methods should be private by default and protected if they
> need access to a base classes version (except for the destructor, of
> course), from http://www.gotw.ca/publications/mill18.htm.
>
> - Header files should be self contained, from various sources.
>
> - Destructors for base classes should be either virtual or protected.
>
> I think I've probably missed (or never heard of) quite a few more.
> Anyone know where I can find such things? Or have some guidelines of
> their own to share?[/color]

Check out these two books:
"Large-Scale C++ Software Design" by John Lakos
"Object-Oriented Design Heuristics" by Arthur J. Riel

This site may also be helpful:
<http://www.chris-lott.org/resources/cstyle/>

[Daniel T.]

Re: C++ Guidelines

Pete Vidler <pvidler@mailbl ocks.com> wrote:
[color=blue]
> I'm wondering if there is a compilation of C++ guidelines out there
> anywhere. Here are some of the ones I've picked up so far (as examples):
>
> - Functions should fit on one screen, from various sources.
>
> - Non-leaf classes should be abstract (have pure virtual methods), from
> More Effective C++, Item 33.
>
> - Virtual methods should be private by default and protected if they
> need access to a base classes version (except for the destructor, of
> course), from http://www.gotw.ca/publications/mill18.htm.
>
> - Header files should be self contained, from various sources.
>
> - Destructors for base classes should be either virtual or protected.
>
> I think I've probably missed (or never heard of) quite a few more.
> Anyone know where I can find such things? Or have some guidelines of
> their own to share?[/color]

Check out these two books:
"Large-Scale C++ Software Design" by John Lakos
"Object-Oriented Design Heuristics" by Arthur J. Riel

This site may also be helpful:
<http://www.chris-lott.org/resources/cstyle/>

[Phlip]

Re: C++ Guidelines

Pete Vidler wrote:
[color=blue]
> I'm wondering if there is a compilation of C++ guidelines out there
> anywhere. Here are some of the ones I've picked up so far (as examples):
>
> - Functions should fit on one screen, from various sources.[/color]

Functions should have 1 to 5 activities. In higher level languages this
translates to 1 to 5 statements, but C++ requires a lot of rigging and
piping.
[color=blue]
> - Non-leaf classes should be abstract (have pure virtual methods), from
> More Effective C++, Item 33.[/color]

The corpus of Addison Wesley [Longman]'s C++ and theory books form the
pinacle of known style. Try /Design Patterns/, /Large Scale C++ Software
Design/, and /Refactoring/.
[color=blue]
> - Virtual methods should be private by default and protected if they
> need access to a base classes version (except for the destructor, of
> course), from http://www.gotw.ca/publications/mill18.htm.[/color]

Also try /Exceptional C++/, by Herb Sutter.
[color=blue]
> - Header files should be self contained, from various sources.[/color]

The implication here is you can always add a new #include "thing.h", and it
takes care of itself. You never need to add another #include above it.
/Large Scale/ covers this in great detail.
[color=blue]
> - Destructors for base classes should be either virtual or protected.[/color]

Never heard of the "protected" one.
[color=blue]
> I think I've probably missed (or never heard of) quite a few more.
> Anyone know where I can find such things? Or have some guidelines of
> their own to share?[/color]

These guidelines occupy a spectrum. At one end, we have requirements that
C++'s minimal expression enforces. Thou shalt make all destructors virtual
unless profiling reveals the need to remove a class's 'vtable'. At the other
end we have team specific patterns and behaviors. For example, one team may
adopt STL for all collection classes, and another may have an alternative
library, hence should not use STL. But we should recommend STL when writing
books for AW.

--
Phlip

http://www.xpsd.org/cgi-bin/wiki?TestFirstUserInterfaces

[Phlip]

Re: C++ Guidelines

Pete Vidler wrote:
[color=blue]
> I'm wondering if there is a compilation of C++ guidelines out there
> anywhere. Here are some of the ones I've picked up so far (as examples):
>
> - Functions should fit on one screen, from various sources.[/color]

Functions should have 1 to 5 activities. In higher level languages this
translates to 1 to 5 statements, but C++ requires a lot of rigging and
piping.
[color=blue]
> - Non-leaf classes should be abstract (have pure virtual methods), from
> More Effective C++, Item 33.[/color]

The corpus of Addison Wesley [Longman]'s C++ and theory books form the
pinacle of known style. Try /Design Patterns/, /Large Scale C++ Software
Design/, and /Refactoring/.
[color=blue]
> - Virtual methods should be private by default and protected if they
> need access to a base classes version (except for the destructor, of
> course), from http://www.gotw.ca/publications/mill18.htm.[/color]

Also try /Exceptional C++/, by Herb Sutter.
[color=blue]
> - Header files should be self contained, from various sources.[/color]

The implication here is you can always add a new #include "thing.h", and it
takes care of itself. You never need to add another #include above it.
/Large Scale/ covers this in great detail.
[color=blue]
> - Destructors for base classes should be either virtual or protected.[/color]

Never heard of the "protected" one.
[color=blue]
> I think I've probably missed (or never heard of) quite a few more.
> Anyone know where I can find such things? Or have some guidelines of
> their own to share?[/color]

These guidelines occupy a spectrum. At one end, we have requirements that
C++'s minimal expression enforces. Thou shalt make all destructors virtual
unless profiling reveals the need to remove a class's 'vtable'. At the other
end we have team specific patterns and behaviors. For example, one team may
adopt STL for all collection classes, and another may have an alternative
library, hence should not use STL. But we should recommend STL when writing
books for AW.

--
Phlip

http://www.xpsd.org/cgi-bin/wiki?TestFirstUserInterfaces

[Pete Vidler]

Re: C++ Guidelines

Daniel T. wrote:
[snip][color=blue]
> Check out these two books:
> "Large-Scale C++ Software Design" by John Lakos[/color]

I've heard of this one, but isn't it seriously out of date? I've also
heard that he has some strange guidelines like not using namespaces?
[color=blue]
> "Object-Oriented Design Heuristics" by Arthur J. Riel[/color]

I'll look into it, thanks.
[color=blue]
> This site may also be helpful:
> <http://www.chris-lott.org/resources/cstyle/>[/color]

Most of the links there appear to be documents detailing naming
conventions and recommending a given style for the placement of braces.
I'm looking for more along the lines of design guidelines like I posted
(there was one good page there though, thanks).

I don't really need the basic stuff (I know most of them), but I am
looking for more advanced guidelines (with justifications, like the one
about making virtual methods private).

Thanks,
-- Pete

[Pete Vidler]

Re: C++ Guidelines

Daniel T. wrote:
[snip][color=blue]
> Check out these two books:
> "Large-Scale C++ Software Design" by John Lakos[/color]

I've heard of this one, but isn't it seriously out of date? I've also
heard that he has some strange guidelines like not using namespaces?
[color=blue]
> "Object-Oriented Design Heuristics" by Arthur J. Riel[/color]

I'll look into it, thanks.
[color=blue]
> This site may also be helpful:
> <http://www.chris-lott.org/resources/cstyle/>[/color]

Most of the links there appear to be documents detailing naming
conventions and recommending a given style for the placement of braces.
I'm looking for more along the lines of design guidelines like I posted
(there was one good page there though, thanks).

I don't really need the basic stuff (I know most of them), but I am
looking for more advanced guidelines (with justifications, like the one
about making virtual methods private).

Thanks,
-- Pete

[Claudio Puviani]

Re: C++ Guidelines


"Pete Vidler" <pvidler@mailbl ocks.com> wrote[color=blue]
> I'm wondering if there is a compilation of C++ guidelines out there
> anywhere.[/color]

http://search.barnesandnoble.com/booksearch/isbnInquiry.asp?isbn=0521893089

It's basically an extension of what used to be Rogue Wave's guidelines. No
one will agree with every guideline, but they're mostly reasonable.
[color=blue]
> Here are some of the ones I've picked up so far (as examples):
>
> - Functions should fit on one screen, from various sources.[/color]

That's really a side-effect of a few more fundamental principles, such as
"maximize cohesion" and "modularize where reasonable." A function that is
very large should raise flags, but there are rare instances where it's
entirely justified to have even extremely large functions (as anyone who's
ever used YACC will testify).
[color=blue]
> - Header files should be self contained, from various sources.[/color]

This one should be shredded or rephrased. Header files have dependencies
just like any other software component, and so can rarely be self-contained.

Claudio Puviani

[Claudio Puviani]

Re: C++ Guidelines


"Pete Vidler" <pvidler@mailbl ocks.com> wrote[color=blue]
> I'm wondering if there is a compilation of C++ guidelines out there
> anywhere.[/color]

http://search.barnesandnoble.com/booksearch/isbnInquiry.asp?isbn=0521893089

It's basically an extension of what used to be Rogue Wave's guidelines. No
one will agree with every guideline, but they're mostly reasonable.
[color=blue]
> Here are some of the ones I've picked up so far (as examples):
>
> - Functions should fit on one screen, from various sources.[/color]

That's really a side-effect of a few more fundamental principles, such as
"maximize cohesion" and "modularize where reasonable." A function that is
very large should raise flags, but there are rare instances where it's
entirely justified to have even extremely large functions (as anyone who's
ever used YACC will testify).
[color=blue]
> - Header files should be self contained, from various sources.[/color]

This one should be shredded or rephrased. Header files have dependencies
just like any other software component, and so can rarely be self-contained.

Claudio Puviani

[Pete Vidler]

Re: C++ Guidelines

Claudio Puviani wrote:
[snip][color=blue]
> http://search.barnesandnoble.com/boo...sbn=0521893089
>
> It's basically an extension of what used to be Rogue Wave's guidelines. No
> one will agree with every guideline, but they're mostly reasonable.[/color]

Interesting.. but the summary says it deals with formatting, naming,
documentation, etc. I was looking for design guidelines along the lines
of those that I posted. Am I correct in assuming it doesn't cover such
issues?
[color=blue][color=green]
>>- Functions should fit on one screen, from various sources.[/color]
>
> That's really a side-effect of a few more fundamental principles, such as
> "maximize cohesion" and "modularize where reasonable." A function that is
> very large should raise flags, but there are rare instances where it's
> entirely justified to have even extremely large functions (as anyone who's
> ever used YACC will testify).[/color]

Yes that example was more basic than I really wanted. Ignore it, I'm far
more interested in guidelines similar to the others that I posted.
[color=blue][color=green]
>>- Header files should be self contained, from various sources.[/color]
>
> This one should be shredded or rephrased. Header files have dependencies
> just like any other software component, and so can rarely be self-contained.[/color]
[snip]

Obviously if a header file is from a library then the library must be
linked to. I meant from a compiler point of view.

More specifically that it should forward declare or #include everything
it requires to compile. I'm fairly sure most people would understand
this from "self contained", but I suppose I should have been more precise.

-- Pete

[Pete Vidler]

Re: C++ Guidelines

Claudio Puviani wrote:
[snip][color=blue]
> http://search.barnesandnoble.com/boo...sbn=0521893089
>
> It's basically an extension of what used to be Rogue Wave's guidelines. No
> one will agree with every guideline, but they're mostly reasonable.[/color]

Interesting.. but the summary says it deals with formatting, naming,
documentation, etc. I was looking for design guidelines along the lines
of those that I posted. Am I correct in assuming it doesn't cover such
issues?
[color=blue][color=green]
>>- Functions should fit on one screen, from various sources.[/color]
>
> That's really a side-effect of a few more fundamental principles, such as
> "maximize cohesion" and "modularize where reasonable." A function that is
> very large should raise flags, but there are rare instances where it's
> entirely justified to have even extremely large functions (as anyone who's
> ever used YACC will testify).[/color]

Yes that example was more basic than I really wanted. Ignore it, I'm far
more interested in guidelines similar to the others that I posted.
[color=blue][color=green]
>>- Header files should be self contained, from various sources.[/color]
>
> This one should be shredded or rephrased. Header files have dependencies
> just like any other software component, and so can rarely be self-contained.[/color]
[snip]

Obviously if a header file is from a library then the library must be
linked to. I meant from a compiler point of view.

More specifically that it should forward declare or #include everything
it requires to compile. I'm fairly sure most people would understand
this from "self contained", but I suppose I should have been more precise.

-- Pete

[David Harmon]

Re: C++ Guidelines

On Sat, 10 Apr 2004 16:16:23 +0100 in comp.lang.c++, Pete Vidler
<pvidler@mailbl ocks.com> wrote,[color=blue][color=green]
>> This site may also be helpful:
>> <http://www.chris-lott.org/resources/cstyle/>[/color]
>
>Most of the links there appear to be documents detailing naming
>conventions and recommending a given style for the placement of braces.
>I'm looking for more along the lines of design guidelines like I posted[/color]

Well, arguing over the placement of braces has less potential for harm
than many of the design guidelines I have seen.

[David Harmon]

Re: C++ Guidelines

On Sat, 10 Apr 2004 16:16:23 +0100 in comp.lang.c++, Pete Vidler
<pvidler@mailbl ocks.com> wrote,[color=blue][color=green]
>> This site may also be helpful:
>> <http://www.chris-lott.org/resources/cstyle/>[/color]
>
>Most of the links there appear to be documents detailing naming
>conventions and recommending a given style for the placement of braces.
>I'm looking for more along the lines of design guidelines like I posted[/color]

Well, arguing over the placement of braces has less potential for harm
than many of the design guidelines I have seen.

[Pete Vidler]

Re: C++ Guidelines

David Harmon wrote:
[snip][color=blue]
> Well, arguing over the placement of braces has less potential for harm
> than many of the design guidelines I have seen.[/color]

Yes, but there's no potential for learning anything with
brace-placement. You can already see the possibilities.

-- Pete

[Pete Vidler]

Re: C++ Guidelines

David Harmon wrote:
[snip][color=blue]
> Well, arguing over the placement of braces has less potential for harm
> than many of the design guidelines I have seen.[/color]

Yes, but there's no potential for learning anything with
brace-placement. You can already see the possibilities.

-- Pete