On Fri, 2004-04-09 at 23:11, robert burrell donkin wrote: > On 9 Apr 2004, at 02:10, Craig McClanahan wrote: > > > matthew.hawthorne wrote: > > > >> Simon Kitching wrote: > >> > >>> What benefit is there in having this info in the source? > >>> I can't currently see any: > >>> * Developers can just use "cvs status". > >>> * End users just care that the file came from "version 2.1". > >>> * Maybe it is useful info when working with source snapshots, > >>> but that isn't very common. > >>> > >>> What am I missing? > >> > >> > >> I think it's a convenience to be able to see when the last change was > >> made, and who made it, in the source file -- instead of doing 'cvs > >> status'. But that's about it. > > I like having the "$Id$" string somewhere at the top of each file, > > because I often download the sources onto my laptop, and can't execute > > "cvs status" from an airplane. > > +1 > > the version doesn't add anything (but distractions ;) to the javadocs > but having an $Id$ tag somewhere is useful (on occasion). > > i think that henri's right about good @since tags being much more > useful. if this was done just before each release, it'd probably be > possible to use a script to add these to every method and every class > (which does not have them already).
Ok, here's a solution I hope will satisfy everyone. Can people please give their opinion on this? There seemed to be general agreement that having this info as @version in the javadoc is not useful, but having it somewhere in the text for developers to refer to is. So I propose that the following is added as the *last* line of every digester .java file: // version: $Id$ This makes it really easy to find, without being intrusive for people studying the code. And "tail -n 1 *.java" will dump the version info for every file in the local dir, which seems useful. [and it will be really easy to automate the process to add the version info :-]. The major drawback I see is that no other project does it this way (that I know of). But someone's got to be first, right? Alternatively, the same line could be inserted between the class javadoc and the class declaration. This places the info in about the same place it was with the @version javadoc approach. Unfortunately when this info is added to the file, it will of course be the same for every single file, just showing the date the "// version" change was made, plus the user who did it. Any suggestions for working around this? Regards, Simon --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
