[Pki-devel] Automatic reformatting and code style

[Ade Lee]

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 {
       ...
   }

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

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

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.

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".
* Member variables should begin with "m". For example, mMemberVariable.

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.

Comments?
Ade

On Wed, 2011-11-23 at 12:26 -0500, Adam Young wrote:
> MIght I highly encourage that we folow the Sun guides,  as it is the Inustry standard in Java,  and it is pretty staightforward.
> 
> ----- Original Message -----
> From: "Ade Lee" <alee at redhat.com>
> To: pki-devel at redhat.com
> Sent: Wednesday, November 23, 2011 10:48:42 AM
> Subject: [Pki-devel] Automatic reformatting and code style
> 
> Hi all,
> 
> It has been decided that the code should go through an automatic
> reformatting on the trunk to ensure that everything matches the
> project's coding standards.
> 
> Prior to this, we need to review the coding standards and confirm that
> they are what we want to use.
> 
> The current coding standards for the project are referenced here:
> http://pki.fedoraproject.org/wiki/PKI_C_Coding_Style
> http://pki.fedoraproject.org/wiki/PKI_Java_Coding_Style
> 
> Some alternative styles: 
> http://freeipa.org/page/Coding_Style (C)
> http://www.oracle.com/technetwork/java/codeconvtoc-136057.html (java,
> sun conventions)
> 
> We should focus on the java coding style first, followed by C. Most of
> the Perl code is mostly going away most likely, so no need to focus on
> that.
> 
> IPA has a style guide for python, which, unless we have another
> compelling reason, we should probably use that:
> 
> http://freeipa.org/page/Python_Coding_Style 
> 
> We'd like to get this resolved soon - so as not to obscure any future
> changes as we do new development.  So, please devote some attention to
> this soon.
> 
> Thanks, 
> Ade
> 
> _______________________________________________
> Pki-devel mailing list
> Pki-devel at redhat.com
> https://www.redhat.com/mailman/listinfo/pki-devel