Coding practices proposals

[ghudson@MIT.EDU]

I'd like to amend the coding practices in the following ways, if they
aren't objectionable.

1. In the "Output parameter handling" section, recommend naming output
parameters with the suffix "_out".  I started doing this at Zhanna's
suggestion some time ago and it feels natural and helpful.  Adjust the
example accordingly.

2. In the same section, recommend outputting structures as pointers
rather than filling in a caller-provided container.  This simplifies
memory management, and the efficiency cost is minor.

3. (Editorial change) Pull "... input parameters should go before
output parameters in the call signature..." into the output parameter
handling section, from where it currently lives in "Misc to be
sorted."

4. Add a new section on memory management:

Memory Management
-----------------

When using pointers, it is common for one copy of the pointer to be
the "owner," through which the memory will eventually be freed, and
for other copies of the pointer to be "aliases."  To minimize the
likelihood of memory leaks and double-frees, observe the following
guidelines when reasonable:

1. When transferring ownership of a pointer (such as when returning an
allocated value to a caller via an output parameter), null out the old
owner pointer unless it is immediately going out of scope.

2. When composing a structure containing pointers, either make every
field an owner or make every field an alias.  If you find yourself
mixing owner fields and alias fields within a temporary structure,
create local variables to act as owners.

3. Initialize variables containing owner pointers to NULL.  Free them
in the function's cleanup handler, even if it would be possible to
free them sooner.