mirror of
https://gitlab.com/fbb-git/cppannotations
synced 2024-11-16 07:48:44 +01:00
777b182edd
This allowed me to standardize the sourcetar and sf/* scripts: the base
directory (containing ./git) is now empty, except for maintenance scripts,
while the source files and build scripts of the annotations are stored in
a subdirectory of their own.
148 lines
6 KiB
Text
148 lines
6 KiB
Text
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.
|
|
|