[Pki-devel] Automatic reformatting and code style

Wed Nov 23 22:05:47 UTC 2011

On 11/23/11 11:57, Ade Lee wrote:
> 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 {
>         ...
>     }
The history behind this probably comes from a nice handy 'vi' shortcut
(pressing ']' twice) that allows for developers to quickly find the 
beginning of
various 'functions' in 'C'/'C++'; note that the opening brace must be a 
standalone
character in the first column for this to work.

This was probably applied to the Java code to find the beginning and 
ending of a
'class' in java files that contained more than one non-nested class in a 
single '.java'
file, so I don't see that big of a problem in changing this for Java -- 
however,
I would prefer that 'C'/'C++' functions/methods retain this handy 
feature, as
not every programmer is particularly fond of IDEs, and I would argue that we
should not require developers to use an IDE such as eclipse.

That being said, I would prefer multiple non-nested public classes to 
reside in their
own files, leaving only cases where we need/require standalone 
private/protected
classes to co-exist within the same file?  I am uncertain if we even 
have any of these.

> 2. We require that interface names begin with "I".  Sun says nothing
> about this.  This is probably a good one to keep.
I agree that we should keep this 'handy' notation.
>
> 3. We specify "no tabs".  Sun says tabs are optional.  We should keep
> this.
My personal preference is to use 'spaces' instead of 'tabs' primarily 
due to the
variable 'tabstop' settings in files.
>
> 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.
I have no particular preference one way or another on this.
>
> 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.
These all seem fine to me.

While I understand Adam's doesn't like Hungarian notation, the
downside of renaming everything will make it far more difficult
for the people who are the most familiar with this code to
continue to make changes.

> 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
>
> _______________________________________________
> Pki-devel mailing list
> Pki-devel at redhat.com
> https://www.redhat.com/mailman/listinfo/pki-devel