Uggh. I hate to be the one to start this thread, but if there are ever more developers it's sure to be a needed one.
My question is about coding style. I pretty much follow the Sun style of coding (I am told, though I've never seen their source). Is this a problem? Should we settle on a consistent style?
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
You bet it's important. I also started thinking about this on the weekend. It is very important I believe to have consistent code; it makes it much more readable and easier to follow between files. Sun's code style is definitely the way to go. I don't know if you've noticed my code yet, but I'm very verbose and organized (at least I try to be :). I treat my code with the same attention as I do with writing a specification. I follow (or at least try to) the Sun spec regarding the important stuff: javadoc, naming conventions, etc.
This is an important topic to discuss at this time. I'll give the spec another read over tonight and I'll comment further on specifics. Are there any particular areas in the current source base that you find stray beyond the spec and need to be addressed? By identitying and discussing these problems we can develop a consistent style for this project.
First problem that comes to mind is the source header I've been using. It needs work. It served the purpose of identifying the license and copywrite holder, but a standard one is needed. I'll be able to provide possible solutions later tonight after going over the Sun spec.
Andrew...
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
This is sort of the standard style of header you find in code covered by the GPL (and LGPL in our case)
/*javax/mail/subpackage/Filename.java
* This class is an abstraction of a filename. It offers
* Copyright (C) 2000 Open Java Extensions, Joseph Lesh, Andrew Aselkirk
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public License
* as published by the Free Software Foundation.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Library General Public License for more details.
*
* You should have received a copy of the GNU Library General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
*/
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
I like it! I've seen the full license added and it is definitely too long, but this one is shorter and to the point about LGPL licensing. For the authors, everyone who has made a contribution to the file should be listed in alphabetical order. Do we need the description in this header? We will have a JavaDoc entry for the class which should adequately describe the class.
I think we should move the authors from the header and put them in the main JavaDoc entry using @author tags because this reference is more important and we don't need to mention everyone twice.
Andrew...
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
<snip>
I think we should move the authors from the header and put them in the main JavaDoc entry using @author tags because this reference is more important and we don't need to mention everyone twice.
</snip>
Totally. As for the description, it would be fine to let that go but having the filename on the first line is suprisingly important.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
Welcome to Open Discussion
Uggh. I hate to be the one to start this thread, but if there are ever more developers it's sure to be a needed one.
My question is about coding style. I pretty much follow the Sun style of coding (I am told, though I've never seen their source). Is this a problem? Should we settle on a consistent style?
You bet it's important. I also started thinking about this on the weekend. It is very important I believe to have consistent code; it makes it much more readable and easier to follow between files. Sun's code style is definitely the way to go. I don't know if you've noticed my code yet, but I'm very verbose and organized (at least I try to be :). I treat my code with the same attention as I do with writing a specification. I follow (or at least try to) the Sun spec regarding the important stuff: javadoc, naming conventions, etc.
This is an important topic to discuss at this time. I'll give the spec another read over tonight and I'll comment further on specifics. Are there any particular areas in the current source base that you find stray beyond the spec and need to be addressed? By identitying and discussing these problems we can develop a consistent style for this project.
First problem that comes to mind is the source header I've been using. It needs work. It served the purpose of identifying the license and copywrite holder, but a standard one is needed. I'll be able to provide possible solutions later tonight after going over the Sun spec.
Andrew...
This is sort of the standard style of header you find in code covered by the GPL (and LGPL in our case)
/*javax/mail/subpackage/Filename.java
* This class is an abstraction of a filename. It offers
* Copyright (C) 2000 Open Java Extensions, Joseph Lesh, Andrew Aselkirk
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public License
* as published by the Free Software Foundation.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Library General Public License for more details.
*
* You should have received a copy of the GNU Library General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
*/
I like it! I've seen the full license added and it is definitely too long, but this one is shorter and to the point about LGPL licensing. For the authors, everyone who has made a contribution to the file should be listed in alphabetical order. Do we need the description in this header? We will have a JavaDoc entry for the class which should adequately describe the class.
I think we should move the authors from the header and put them in the main JavaDoc entry using @author tags because this reference is more important and we don't need to mention everyone twice.
Andrew...
<snip>
I think we should move the authors from the header and put them in the main JavaDoc entry using @author tags because this reference is more important and we don't need to mention everyone twice.
</snip>
Totally. As for the description, it would be fine to let that go but having the filename on the first line is suprisingly important.
Yes, I concur. We can leave the filename in the header as this seems appropriate. We'll move the authors and description into the main JavaDoc entry.