[Pki-devel] Automatic reformatting and code style

[Adam Young]

>I looked at our current guidelines and noticed the following differences
>with the Sun guides:
>
>1. Placement of braces 
>In the current coding guidelines, we say classes and methods should look
>like this:
>   public class MyClass
>   {
>       ...
>   }
>
>instead of this (as in the Sun standard):
>   public class MyClass {
>       ...
>   }

Yes please;


>2. We require that interface names begin with "I".  Sun says nothing
>about this.  This is probably a good one to keep.

NO!
This should go away.
We definitely have too many interfaces.  If there is only one Impl,  we should merge Impl and interface.
Hungarian notation is a crimae against Humanity.  The interface should get the Good, simple name,  and  the Impl  sould get whatever makes it special.


>3. We specify "no tabs".  Sun says tabs are optional.  We should keep
>this.

Agreed.  No tabs

>4. We say "Static methods should begin with a capital letter with each
>subsequent new word in uppercase, and subsequent letters in each word in
>lower case.  Sun has no special treatment for static methods - ie. they
>are treated just like other methods .. ie. beginning with a lower-case
>letter.

lowercase the first letter.  It is what everyone expects.

>5. We do have some guidelines for naming functions that go beyond what
>Sun specifies - and also perhaps, beyond what eclipse can verify.
>
>For example:  
>*   Get and set methods should begin with "get" / "set" and return the
>appropriate object type.
>*   Boolean get methods should use "is" or "can" as a prefix, such as
>"isUndoable()" rather than "getUndoable()".
>* Factory class names should include the word "Factory". Factory method
>names should start with the word "Make."
>* Methods for debug-only implementations should begin with "debug".

These are all fine.  
get/set is the bean API.  While I am not a fan, doing this does make things work with automated tools.


>>* Member variables should begin with "m". For example, mMemberVariable..


'm' should go away.  Again,  hungarina notation,  obfusticates the code, and makes it hard to read.

>My take on this is that we should adopt the Sun coding standards and add
>the additional requirements that make sense - like the ones listed in
>point 5 above.  For the cases where we conflict with the Sun standards,
>we should go with the Sun standards instead.

Agreed.  I'd like to exorcise the Hungarian naming conventions,  but that can be done over time.  Code is meant to be readable,  and all HN  does is obfuscate.  It is not necessary in Java.  I am pretty sure it is explictly against the Sun Java Conventions.


http://www.oracle.com/technetwork/java/codeconventions-137265.html#587

There is one thing I don't really agree with.  It is not only OK to make member variables public,  it is a best practice,  provided that you make them final.




Instead of  
private String namel
public String getName(){
return name;
}

it should be 


public final String name;

public MyObject(String name){
this.name = name;
}


What this means is that instance variables are set in the constructor where ever possible.   In general,  we should favor immutable objects, as they are inherantly thread safe.  It also means that we use the constructor to confirm that a given object complies with its contract.  This is in Keeping with JOshua Block'ss  advice in "Evffective Java"  which should be required reading.