Hi,
I’d also like to add to this list….
Please do not use wildcard imports such as the following:
import java.util.*;
It is considered bad coding practice:
http://seanmonstar.com/post/708954358/import-star-considered-harmful
Another thing about documentation. Please add yourself as an author if you make any significant changes to a class beyond reformatting it.
Having multiple author tags is fine and it helps to show who has worked on the file.
—Jeremy
On Oct 25, 2013, at 12:59 PM, McCormick, Jeremy I. <[log in to unmask]> wrote:
> Hi,
>
> I wanted to provide some guidelines on coding in Java, as I’m seeing some things in hps-java that are a bit ugly.
>
> Firstly, while I understand we all have our preferences in terms of style, it would be good if we could standardize as follows.
>
> class Something {
> public void something() {
> if (true) {
> System.out.println(“blah”);
> }
> }
> }
>
> Basically, brackets should not be put on their own line. Indentation should be 4 spaces. (Please turn OFF completely tabs in your IDE so they are replaced automatically by spaces.)
> This is AFAIK something like the Java standard.
>
> Please at least include the following in your class documentation…
>
> -A brief description of what the class does.
> -An author tag with your name and email.
> -A version tag with the cvs id.
>
> This would look something like the following…
>
> /**
> * This class does something really special.
> * @author Jeremy McCormick <[log in to unmask]>
> * @version $id: $
> */
> class SpecialClass {
> }
>
> Most IDEs including Netbeans and Eclipse will let you setup a template for doing this automatically.
>
> Ideally ALL methods should be documented as well...
>
> /**
> * This method does something special
> * @param thing A thing
> * @return Another thing
> * @throws IllegalArgumentException if the the argument is not special.
> */
> public void doSomethingSpecial(Object thing) {
> if (thing == null) {
> throw new IllegalArgumentException(“Thing is not special.");
> }
> return anotherThing;
> }
>
> There are a bunch of classes where the “@Override” statements seem to have been put in automatically by the IDE and left in the source code. Please make sure you remove these when committing the code.
>
> I will go ahead and correct some of this stuff but it might be a good idea for everyone to revisit their old code and improve it.
>
> —Jeremy
> ########################################################################
> Use REPLY-ALL to reply to list
>
> To unsubscribe from the HPS-SOFTWARE list, click the following link:
> https://listserv.slac.stanford.edu/cgi-bin/wa?SUBED1=HPS-SOFTWARE&A=1
########################################################################
Use REPLY-ALL to reply to list
To unsubscribe from the HPS-SOFTWARE list, click the following link:
https://listserv.slac.stanford.edu/cgi-bin/wa?SUBED1=HPS-SOFTWARE&A=1
|