Re: ChangeLog format (not really Re: S/390: Fix backtrace supportfor Java)

[Michael Matz <matz at suse dot de>]

Hi,

On Wed, 2 Apr 2003, Hans-Peter Nilsson wrote:

> > times.  Not all of those entries reflect usage like above,
>
> Try "almost none of them".  Your grep statistics are totally
> misleading.

No they aren't.  There are false positives in both numbers.  For instance
it matches
  ChangeLog.0:    use varargs.h.  Wrap header with <>, not "".
and also
  ChangeLog:      (walk_type): Update prev_val[3].

But as I already said, if one looks at the output of the above greps there
are clearly more [] for naming function parts, than <>.  For instance for
./ChangeLog alone there are 8 correct uses of <> and 10 uses of [], where
per your reading <> should have been used.  For older ChangeLogs the
difference is even higher, for instance ChangeLog.0 has exactly zero
correct uses of <>, but 10 [] uses to name a part.

> > verifying them reveals that most of them fit here.  The use of [] dates
> > back until FSFChangeLog.11, 1997.
>
> For FSFChangeLog.11, most [] come from regex/glob abominations
> like ({sparc,i[3456]86,powerpcle}-*-solaris2*) and almost none
> from incorrect use.  Actual <> and [] use as per coding
> standards (or your suggested change) disappear in the noise.

You will notice that the above grep's only look at ChangeLog*, not
FSFChangeLog, but for those you are correct, there are not many correct
usages, but there are some (see below).

> > "part" of a function is not further defined.  From 1) and 2) above does
> > not follow, that for switch cases specifically <> should be used, or that
> > [] is not allowed.
>
> Well, the switch case is clearly a *part*,

Like the #ifdef'ed portion is also a part.  Just that for that one the
standards have a different convention.

> and clearly not a *conditional change*.  I don't understand your "1)
> and 2) above"-interpretation; I don't see a [] vs. <> ambiguity at
> all. Can you explain your reading please (for C/C++ code)?  Maybe
> others are as dense and would be helped. ;-)

Well, the problems begin with the inexact definition of "part".  An #ifdef
portion is a part, still the standards authors saw the need to draw a
difference.  One sourceline also is a part, but clearly it's useless to
write "(some_function) <1452>".  This makes the definition of when to
write <> quite useless.  I usually read this as "part of function which
doesn't correspond strictly to syntax elements", like "<first half>" or
"<above initialization>", or generally descriptions which contain more
than one word, i.e. also "<if (a_condition)>", i.e. the inexact definition
of when to use <> makes me use it only, when the part can not be
described exactly.

But if a certain part can be "named" by a simple identifier, like in
switch cases, #ifdefs and so on, I use [].

> down to be one way and not the other.  If you agree the two are
> visually equivalent,

I didn't write this.  I said, that in the function of marking their
content in an easily spotted way, they are equal.  This doesn't make them
visually equivalent, and in fact I find [] more pleasing.

> > Additionally, standards should standardize common practice, instead of
> > imposing artificial restrictions, and from the above numbers it's clear
> > what the common practice is.
>
> Totally not clear.  Did you look at the actual grep matches for
> example (since you mentioned it) for FSFChangeLog.11?

Yes, I did.  But the numbers above are only for ChangeLog*.  Just out of
couriosity I also looked at FSFChangeLog.11 to find the first use of [] to
name a part, and it is (from 1997-12-08):
        * make-cccp.com [CC]: Add /Prefix=All for DEC C.
There are actually zero uses of <> to name a part.  From FSFChangeLog.11
these lines match the grep expression:
        use varargs.h.  Wrap header with <>, not "".
        * sparc.md: TARGET_<code_model> renamed to TARGET_CM_....
        (REGISTER_MOVE_COST): Add costs for fpul <-> mac, pr moves.
        DMGL_JAVA.  Thus "::" becomes "." and "JArray<Foo>" becomes "Foo[]".
        * loop.c (maybe_eliminate_biv_1): In (set (cc0) <biv>) case,
        has been declared.  Process "%include <file>" to include another
        "%include_noerr <file>: to include another specs file, giving no
        * ginclude/{stdarg.h,varargs.h}: Use #include "", not #include <>.
        for C++, to avoid conflict with <exception>.
        place a bl <func> in the appropriate section.
        * c-parse.in (typespec): Made <SomeProtocol> equivalent
        to (id <SomeProtocol>).

> Why not propose to adjust the GNU coding standards instead?

Yes, hmm.  Usually trying to change standards is hard work, and I'm lazy
;-)

> The "fact" you seem to refer to I think is just recent copycat misuse.

Definitely not recent.

> it, instead we should just correct erroneous uses.  Doh!  :-)

:-P ;)


Ciao,
Michael.