[Coding rules] Author/Creator information
Hi everyone, Do you really want to keep the following which is part of most file headers: * Created by * User: Ludovic Dubost * Date: 26 nov. 2003 * Time: 13:52:39 This seems to me information that can be retrieved from the SCM. And if we want to store SCM information in the file then it is only fair that whoever modifies the file should also get credit there. In addition usually we would use the @author tag for storing this kind of information. Having it in an undefined format like above is a bit strange... ;-) So I think there are 2 options: Option 1: --------- - We do not store author information in the file - We have a credits Wiki page that lists all contributors and what they have done. Something like: - http://jakarta.apache.org/cactus/participating/contributors.html - http://cargo.codehaus.org/Credits - It's still a good idea to have a @version tag in the file, as in: * @version $Id: Container.java 348 2005-04-26 23:03:22Z vmassol $ The content of this tag is generated automatically by the SCM upon commit. Option 2: --------- - We save author information in the file using @author tags. For example @author <a href="mailto:...@...">Ludovic Dubost</a> @author <a href="mailto:...@...">Vincent Massol</a> [...] There have been *lots* of debates (which I'll spare you here but you can google it) between these 2 options and the one chosen @ Apache is option 1. I have done the same for Cargo. I don't mind the chosen solution but I think the current option is not good enough. Thanks -Vincent _____________________________________________________________________________ D�couvrez le nouveau Yahoo! Mail : 1 Go d'espace de stockage pour vos mails, photos et vid�os ! Cr�ez votre Yahoo! Mail sur http://fr.mail.yahoo.com
I'd vote for option 1. SCM is good enough for detailed information. And a contributors page is good.. Ludovic Vincent Massol a écrit :
Hi everyone,
Do you really want to keep the following which is part of most file headers:
* Created by * User: Ludovic Dubost * Date: 26 nov. 2003 * Time: 13:52:39
This seems to me information that can be retrieved from the SCM. And if we want to store SCM information in the file then it is only fair that whoever modifies the file should also get credit there. In addition usually we would use the @author tag for storing this kind of information. Having it in an undefined format like above is a bit strange... ;-)
So I think there are 2 options:
Option 1: ---------
- We do not store author information in the file - We have a credits Wiki page that lists all contributors and what they have done. Something like: - http://jakarta.apache.org/cactus/participating/contributors.html - http://cargo.codehaus.org/Credits - It's still a good idea to have a @version tag in the file, as in:
* @version $Id: Container.java 348 2005-04-26 23:03:22Z vmassol $
The content of this tag is generated automatically by the SCM upon commit.
Option 2: ---------
- We save author information in the file using @author tags. For example
@author <a href="mailto:...@...">Ludovic Dubost</a> @author <a href="mailto:...@...">Vincent Massol</a> [...]
There have been *lots* of debates (which I'll spare you here but you can google it) between these 2 options and the one chosen @ Apache is option 1. I have done the same for Cargo.
I don't mind the chosen solution but I think the current option is not good enough.
Thanks -Vincent
_____________________________________________________________________________ Découvrez le nouveau Yahoo! Mail : 1 Go d'espace de stockage pour vos mails, photos et vidéos ! Créez votre Yahoo! Mail sur http://fr.mail.yahoo.com
------------------------------------------------------------------------
-- You receive this message as a subscriber of the [email protected] mailing list. To unsubscribe: mailto:[email protected] For general help: mailto:[email protected]?subject=help ObjectWeb mailing lists service home page: http://www.objectweb.org/wws
-- Ludovic Dubost XPertNet: http://www.xpertnet.fr/ Blog: http://www.ludovic.org/blog/ XWiki: http://www.xwiki.com Skype: ldubost AIM: nvludo Yahoo: ludovic
participants (3)
-
Alexis KARTMANN -
Ludovic Dubost -
Vincent Massol