This is the mail archive of the java-patches@gcc.gnu.org mailing list for the Java project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

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


Oh, just one more...

On Thu, 3 Apr 2003, Michael Matz wrote:
> 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.

To me, what statistics you try to collect are useful only to
show that there's actually a need to point out what style is
expected; what they should read themselves in the GNU coding
standards at pages
<URL:http://www.gnu.org/prep/standards_44.html#SEC44> and
<URL:http://www.gnu.org/prep/standards_45.html#SEC45>, the
document linked from contribute.html.

Arguing that the amount of misuse is a reason to override the
documented style, but *not* changing the style document, is
faulty.

> > 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.

Ah!  It seems we now agree on the reading...  Good. :P

> 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>".

Well, duh.

>  This makes the definition of when to
> write <> quite useless.

For me, "the part of a function which changed" is a sufficient
definition.  It's not like you *have* to use it; most often it's
redundant.  But sometimes it's hard to spot the location of the
change from the function name and the ChangeLog text.  A
function name or equivalent may not even be applicable.  Then,
if there's a short location description that fits, using <> is
useful.

>  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.

That's a good description.  Despite the current focus ;-) <>
*doesn't* need to be used very often.  Still, for code with
large switch-statements, a <case N> usually fits very well.
(And again, [] does *not* fit, because that notation is reserved
for the condition for #if/#ifdef:d code.)

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

When you do so for anything else than #ifdef:s, you're doing it
in opposition to the standard.  It's confusing to have one thing
documented and doing another.  Please don't add to confusion
caused by existing misuse.

> > 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.

That's your opinion, but doing so generally is incorrect.

> > Why not propose to adjust the GNU coding standards instead?
>
> Yes, hmm.  Usually trying to change standards is hard work, and I'm lazy
> ;-)

Then just follow what is documented.  Please.  Arguing that we
shouldn't follow the standard we're supposed to follow when
incorrect use is pointed out, leads to more work for you.

Again, either the standard or the misuse should be fixed.  If
you think the standard is hard to fix, then fix the misuse.

brgds, H-P


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]