Re: failure to build due to ignoring fwrite() result

[Bruno Haible]

Karl, all,

>   @pindex lint
> ! Don't make the program ugly to placate @code{lint}.  Please don't insert any
> ! casts to @code{void}.  Zero without a cast is perfectly fine as a null
> ! pointer constant, except when calling a varargs function.

Here is a proposed wording that
  - acknowledges the fact that there are different opinions among GNU
    maintainers (Chet Ramey wants few warnings, I use just -Wall, Jim
    uses also -Wshadow and some more, and Simon uses many more),
  - nevertheless tries to give reasonable advice.

Paul's mention of valgrind is a good one, because just like some people
ask us to remove all warnings that occur with -Wundef, others ask to
free all memory before a program exits, as a way to placate valgrind.

At first I wanted to propose this new paragraph:

-------------------------------------------------------------------------
@cindex warnings, dealing with
@pindex gcc
@pindex valgrind
@pindex clang
@pindex lint
Don't make the program ugly just to placate warnings from tools other
than those that you use on a daily basis.  @code{gcc}'s warnings,
@code{valgrind}'s memory leak checker, @code{clang}'s static analysis
facilities, and code style checkers like @code{lint} can be valuable
tools.  But if you try to placate too many warnings, the readability
of the code will deteriorate.  Some people regularly use
@samp{gcc -Wall}; others use warning options like
@samp{gcc -Wall -Wshadow -Wmissing-prototypes -Wstrict-prototypes}.
Once you have chosen the set of warning options, try to reduce the
resulting warnings to a minimum, so that you will notice when new
code produces new warnings.  But you don't need to get rid of warnings
produced by @samp{-Wundef} or @samp{-Wconversion} because these warnings
rarely point to bugs.

Similarly, not every ``lost memory block'' as reported by @code{valgrind}
is a memory leak.  Memory that is allocated once only and that does not
grow in size as the program runs is not a memory leak.  You don't need to
free such memory before the process exits, even if that would make
@code{valgrind} more silent.
-------------------------------------------------------------------------

but then realized that the advice about valgrind better belongs in the
section about memory use, and there is already a paragraph about compiler
warnings. So I would propose this change.


        * standards.texi (Memory Usage): Add a paragraph about valgrind.
        (Syntactic Conventions): More advice about warnings. Remove paragraph
        about lint.

--- doc/standards.texi.orig     Wed Sep  1 01:25:45 2010
+++ doc/standards.texi  Wed Sep  1 01:24:09 2010
@@ -2322,6 +2322,15 @@
 If your program creates complicated data structures, just make them in
 memory and give a fatal error if @code{malloc} returns zero.
 
address@hidden valgrind
address@hidden memory leak
+The @code{valgrind} tool contains a memory leak detector.  But not every
+``lost memory block'' as reported by @code{valgrind} is a memory leak.
+Memory that is allocated once only and that does not grow in size as the
+program runs is not a memory leak.  You don't need to free such memory
+before the process exits, even if that would make @code{valgrind} more
+silent.
+
 @node File Usage
 @section File Usage
 @cindex file usage
@@ -2623,6 +2632,8 @@
 
 @cindex compiler warnings
 @cindex @samp{-Wall} compiler option
address@hidden warnings
address@hidden gcc
 Some programmers like to use the GCC @samp{-Wall} option, and change the
 code whenever it issues a warning.  If you want to do this, then do.
 Other programmers prefer not to use @samp{-Wall}, because it gives
@@ -2630,6 +2641,16 @@
 If you want to do this, then do.  The compiler should be your servant,
 not your master.
 
address@hidden clang
address@hidden lint
+Don't make the program ugly just to placate warnings from tools other
+than those that you use on a daily basis.  Extra GCC warnings options,
address@hidden's static analysis facilities, and code style checkers like
address@hidden can be valuable tools.  But if you try to placate too many
+warnings, the readability of the code will deteriorate.  For example,
+you don't need to get rid of warnings produced by @samp{gcc -Wundef} or
address@hidden -Wconversion} because these warnings rarely point to bugs.
+
 Declarations of external functions and functions to appear later in the
 source file should all go in one place near the beginning of the file
 (somewhere before the first function definition in the file), or else
@@ -2647,6 +2668,7 @@
 all its uses.  This makes the program even cleaner.
 
 Don't use local variables or parameters that shadow global identifiers.
+GCC's @samp{-Wshadow} option can detect this kind of mistake.
 
 @cindex multiple variables in a line
 Don't declare multiple variables in one declaration that spans lines.
@@ -2750,11 +2772,6 @@
   fatal ("virtual memory exhausted");
 @end example
 
address@hidden lint
-Don't make the program ugly to placate @code{lint}.  Please don't insert any
-casts to @code{void}.  Zero without a cast is perfectly fine as a null
-pointer constant, except when calling a varargs function.
-
 @node Names
 @section Naming Variables, Functions, and Files