4:05 p.m.
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(a)redhat.com>
> To: pki-devel(a)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(a)redhat.com
> https://www.redhat.com/mailman/listinfo/pki-devel
_______________________________________________
Pki-devel mailing list
Pki-devel(a)redhat.com
https://www.redhat.com/mailman/listinfo/pki-devel