Hi,
On Thu, Sep 2, 2010 at 9:23 AM, Paul Eggert <egg...@cs.ucla.edu> wrote:
> 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
We're looking for weasel words that allow for some defensive markups,
but discourage severe uglification. Some phrasing that means, "if it isn't
very ugly, go ahead; but if it is ugly, then it must be to placate a very
often and commonly used tool (viz. gcc?) In brief, use common sense."
For example, void casting fwrite(), were it actually effective. :}
> 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.
Small, commentary annotations: /*lint e:152*/
I think that rates low on the ugly scale.
Macro wrappers: ignore_return(fwrite(...));
pretty high. No. Really High.
> 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.
It needs to depend on the ugly scale for the particular annotation. :)
> 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.
+ Liberally use the "this is okay" feature in the valgrind
configuration file instead.
> �...@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.
> + do-nothing functions merely to pacify GCC with extra warnings.
GCC _is_ the source of the warning that triggered this email fest.... :)
