cppannotations/esr.rejected

2.2.3..2 "It is strongly advised": Avoid passive voice.  Better "We
strongly advise you".  The editorial/royal "we" is quite acceptable in
a single-author document of technical nature, and especially in one
like this with many contributors.


Either after 2.3 or 2.4 (probably the latter) I think it would be wise
to insert a warning.  Here's a suggested text.  I'm putting in a cite to
my book only because as far as I know nobody else has written down the kind
of warning that would be useful here in as much detail as I have,

    The Peril of "C++ Disease"

    Like C++ itself, object-oriented programming has sometimes been
    oversold by its proponents.  Objects are not a magic bullet for the
    problem of code complexity, and spaghetti inheritence is not an
    improvement on spaghetti code.  And, unfortunately, there is some
    evidence that C++ particularly tends to lead programmers into 
    coding overcomplex and rigidly cross-dependent classes.

    For a discussion of the general problem, see the discussion of
    "Unix and Object-Oriented Languages" in Eric S. Raymond's "The Art
    of Unix Programming"; you can read it on the Web at
    <http://www.catb.org/esr/writings/taoup/html/unix_and_oo.html>.  The
    same book has a more specific critique of C++ which you can read here:
    <http://www.catb.org/esr/writings/taoup/html/ch14s04.html#cc_language>.
    Raymond builds on work by Les Hatton and other to suggest that the
    baroqueness of C++ makes projects written in it especially
    vulnerable to overcomplexity.

    You may be able to prevent "C++ disease" on your project by being
    careful and minimalist in your use of the language.  Don't use
    advanced features of the language just because you can.  Instead, 
    always ask if doing so increases or decreases the readability 
    and maintainability of the code.  Also, be wary of class
    hierarchies that embody fancy programming patterns at the cost 
    of composing classes so tightly  to each other that they effectively 
    become one large lump, defeating the very purpose of class encapsulation.

The second cite to tAOUP points at the place where I cited "C++
Annotations".




3.3.1 "In this section the type bool is introduced." It is probably
worth noting here that bool was backported to C in C99.



Chapter 4:

You should give this a good going-over to get rid of passive voice.


Chapter 5:

5.4.3 "In order to  write information to memory, using the stream
facilities, ostringstream objects can be used." Get rid of passive 
voice. "To write information to memory using the stream facilities,
use ostringstream."


5.5.3: You need more passive-voice fixes here.


Chapter 12:


Introduction "If the  data elements of containers are pointers, the
data pointed to by these pointers will not be destroyed, resulting in
a memory leak."  This and other problems noted elsewhere in the 
Annotations suggest a general rule: Don't use C pointers!

This observation should probably go with "Don't use malloc and free"
in a warning section at the end of chapter 2.  Here is a proposed text:

    C practices to leave behind

    C++ tries to hide and semi-automate the details of memory management
    in objects as much as is possible in a statically compiled language.
    It also tries to be upward-compatible with C, notably by supporting
    C-style pointers.

    Unfortunately, these goals are fundamentally incompatible.  C-style
    pointers create referential links among objects that C++'s object
    facilities won't know how to manage properly.  In later chapters
    we'll describe a lot of specific places this can get you into trouble,
    causing memory leaks and dangling pointers and lots of subtle, nasty bugs.

    Two simple rules of thumb will help you avoid all these problems:

    * Don't use C pointers.  Instwed, instantiate objects and pass them 
    by reference.

    * Don't use malloc/realloc/free.  Use object creation, new, and delete
    instead.

    In some cases, C pointers can be replaced with the STL auto_ptr 
    type, which we'll cover in Chapter 17.


12.3.2: "Actually, in my experience, lists aren't that useful at all,
and often an implementation will be faster when a vector, maybe
containing holes, is used." "at all" is unnecessary and can be dropped.

I would actually recommend promoting that observation out of its
context and reworking the beginning of 12.3,2.  Suggested text:

    12.3.2: The `list' container

    The list container implements a classic linked-list data structure.
    It is a bit of a historical relic left over from a time when machines
    were much slower and more memory-constrained.  While it may still
    occasionally be useful (say, in embedded systems for lists with a very
    stereotyped and non-random access pattern) modern practice favors the
    more flexible vector type (among other things, vectors are contiguous
    spans of memory that make better use of cache locality).  You should
    know that the list container exists, but use cases for it will be
    rare (we do discuss them towards the end of this section).

    Before list containers can be used the following preprocessor
    directive must have been specified:

12.3.6: "The map class implements a (sorted) associative array." Add:
"Python and Perl programmers can think of this as a type-checked analogue
of the dictionary features in those languages, and it has many of
the same uses."


Chapter 14:

14.5 "The possibilities of C++'s run-time type identification are
limited compared to languages like Java.": Add "or Python".

14.5.2 "Actually, the typeid operator returns an object of type
type_info, which may, e.g., be compared to other type_info
objects.": Add "This is closely analogous to, e.g., the "type()"
function in Python."

Chapter 15:

This probably needs at its head a reiteration of the warning that
using C pointers at all in C++ is a bad idea, likely to lead to memory
leaks if deallocation isn't handled wit extra care and thus best avoided.

    Has nothing to do with `C pointers': no allocation takes place here.