[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Bug-gnulib] suggestion

From: Bruno Haible
Subject: Re: [Bug-gnulib] suggestion
Date: Sat, 7 Jun 2003 18:43:25 +0200
User-agent: KMail/1.5

Hi Jim,

> I noticed you didn't apply parts of the recent stdbool patch.
> Maybe you'd like some justification?

Yes I usually don't apply seemingly redundant patches to documentation
or comments, when no justification is mentioned. Otherwise, one person
would send me a patch making a sentence a little more verbose and the
next person would send me a patch making it a little more concise.

> It is better to use $@ whenever possible,
> to reduce duplication (ease maintenance).

But in VPATH builds, $@ can also refer to a file in $srcdir,
if it already exists there, right? And here it is mandatory that
stdbool.h is created in $builddir. This minimizes the risk of
totally screwed builds if the $srcdir is not completely clean
and a VPATH build is attempted.

> sed's '<' is unnecessary.
> Removing it also shortens the line.

I used '<' because it's more natural to me. It's not worth
fighting about.

> And I've been taught that comments are best
> written in the imperative.

In GNU, function comments use imperative style
("Set the width to N") whereas some professional documentation
writers recommend the descriptive style ("Sets the width to N").

> In particular,
> I try to avoid using the passive voice.

Yes I recall the professional documentation writers also recommend
this. I'm now changing all "The following is needed ..." to "We need the
following ..."

> As for the `-t' vs. `t' suffix, I don't care much,
> as long as we're consistent, but do have a slight preference
> for the shorter one.

Whereas I have a preference for the longer one (my usual anti-perl
attitude, you know :-)). I agree with the consistency argument, so
I've now committed the patch that I announced on 2003-05-26 and for
which I got no veto.


reply via email to

[Prev in Thread] Current Thread [Next in Thread]