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

[Paul Eggert]

Bruno's proposed changes are mostly good, but I have a few quibbles:

> +Don't make the program ugly just to placate warnings from tools other
> +than those that you use on a daily basis.

This isn't quite right.  Suppose a programmer uses 'lint' on a daily
basis?  They they can make a program ugly to placate 'lint'.  We need
a different way to characterize these tools.  I suggest being more
specific, and saying "programs like lint, clang, and GCC with extra
warnings options such as -Wconversion and -Wundef".

A few other things.  First, it is helpful to retain the specific
example of casting to void to show readers what sort of ugliness we
have in mind; otherwise, the instructions are too vague.

The "Zero without a cast is perfectly fine as a null-pointer constant,
except when calling a varargs function." is a comment on the preceding
code which does just that, so it should probably stay (or the
preceding code rewritten).

Ludovic mentioned Splint, but that's so rarely used and so little
known that it's better to say 'lint', a common collective name
for style checkers.

Here's a proposed rewrite that tries to take all the comments in mind,
while trying to improve the prose a bit.

*** old/standards.texi  Tue Aug 24 10:42:55 2010
--- new/standards.texi  Thu Sep  2 09:14:39 2010
***************
*** 2322,2327 ****
--- 2322,2334 ----
  If your program creates complicated data structures, just make them in
  memory and give a fatal error if @code{malloc} returns zero.
  
+ @pindex valgrind
+ @cindex memory leak
+ Memory leak detectors such as @command{valgrind} can be useful, but
+ don't complicate a program merely to avoid their false alarms.  For
+ example, if memory is used until just before a process exits, don't
+ free it simply to silence a leak detector.
+ 
  @node File Usage
  @section File Usage
  @cindex file usage
***************
*** 2630,2635 ****
--- 2637,2653 ----
  If you want to do this, then do.  The compiler should be your servant,
  not your master.
  
+ @pindex clang
+ @pindex lint
+ Don't make the program ugly just to placate static analysis tools such
+ as @command{lint}, @command{clang}, and GCC with extra warnings
+ options such as @option{-Wconversion} and @option{-Wundef}.  These
+ tools can help find bugs and unclear code, but they can also generate
+ so many false alarms that that it hurts readability to silence them
+ with unnecessary casts, wrappers, and other complications.  For
+ example, please don't insert casts to @code{void} or calls to
+ do-nothing functions merely to pacify a lint checker.
+ 
  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,2652 ****
--- 2665,2671 ----
  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 problem.
  
  @cindex multiple variables in a line
  Don't declare multiple variables in one declaration that spans lines.
***************
*** 2750,2759 ****
    fatal ("virtual memory exhausted");
  @end example
  
! @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.
  
  @node Names
  @section Naming Variables, Functions, and Files
--- 2769,2777 ----
    fatal ("virtual memory exhausted");
  @end example
  
! This example uses zero without a cast as a null pointer constant.
! This is perfectly fine, except that a cast is needed when calling a
! varargs function or when using @code{sizeof}.
  
  @node Names
  @section Naming Variables, Functions, and Files