Aric Stewart aric@codeweavers.com writes:
I think this is part of what the change log is for.
Alexandre has committed the patch, i will ask him if he wants me to document something further and submit another patch.
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.
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.
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.
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.
Jer
Jeremy White jwhite@codeweavers.com wrote in message news:3BAB95E0.2020608@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
-
Alexandre Julliard -
Bill Medland -
Jeremy White