wsprintf

[Bill Medland]

Jeremy White <jwhite at codeweavers.com> wrote in message
news:3BAB95E0.2020608 at codeweavers.com...
> >
> > I added a comment in wsprintf16 to make Andreas happy. But I agree
> > that the change log (and cvs diff) is the best way to store this kind
> > of information.
>
>
>
> Okay, so it's a slow news day, and I feel like stirring up trouble.

Seems like a reasonable idea for a Friday afternoon

>
> I would argue that it is, in fact, counterintuitive, to have this
> sort of comment solely in the change log.  The only time I ever think
> to look at a diff (or even the change log) is when something has broken
> recently.

I agree in general, but I believe that such information is required (in two
different forms) in both places.  (In this particular case what is in the
cvs seems fine to me, but to a large extent we have Alexandre to thank for
keeping that tidy).

>
> IMO, it is appropriate to comment in the code,
> whenever something useful about Wine/Windows behavior is learned,
> especially when the knowledge is something non intuitive
> like the fact that the 16 bit version and 32 bit version
> behave differently.

Here's my views

The change log and cvs diff should explain why a change was made (and in an
ideal world should refer to the supporting documentation e.g. bug numbers
etc.).  In this particular case it should mention, as it does, that the
difference has been detected.

The code should not contain change information.  (I have worked on large
code without the benefit of version control; it's revolting!).  Comments in
the code ought to reflect its current state, not how it got there.  They
should highlight important information that is not obvious (and what may be
obvious to you may not be obvious to someone else or, more worryingly, may
be obviously something else to them).  Thus when two pieces of code look
extremely similar but not identical it is worth a quick comment that the
difference is deliberate, not the result of poor maintenance.  (And I am a
firm believer in doubly linked comments; e.g. one place contains the comment
and the other refers to it).

So what does anyone else think?

Bill