code conventions

Can somebody please tell me, which Java code conventions are the best?
Regards, Simon

5 comments
Comment actions Permalink

Hi Simon,

As a generally rule, I would suggest to start with SUN's code conventions:

- packages are all lowercase: com.company.product.subpackage
- classes/interfaces are concatenated title-case: OurCoolClass
- constants (static final fields) are all upper-case separated with
underscores: THIS_IS_A_CONSTANT
- fields and methods are concatenated title-case starting lower-case:
outputStream

Then you definitely should decide whether to use tabs, space or a smart
mixture of them. Except for the latter case, you also need to define the tab
size. (We use smart tabs, at the moment a IDEA-only option, because our
developers prefer to use different tab-sizes: one likes 4, one 2 spaces per
tab; only with these option the code looks nice with all tab sizes)

Then, some developers like to add a prefix to parameters or field. We use
Java's "this" to reference fields. Example:

private int x;

public void setX(int x) {
this.x = x;
}

This looks in our eyes better than the (unsymmetric) prefixed variant:

private int m_x;
public void setX(int x) {
m_x = x;
}

Also, you should define where to place the opening and closing braces and
whether to use them for single statements. We have choosen this way:

while (a > 0) {
a = next();
if (a == -1) {
return;
}
}

over this:

while (a > 0)
{
a = next();
if (a == -1) return;
}

Why we did that? Placing the opening brace at the end of the line saves
always one line of code. Surrounding all (even single) statements with
braces makes them more obvious, so you can't easily oversee the "return" in
the example above.

There are many, many more rules you can define and set up in IDEA. I would
suggest to pick those, which makes your developers most productive, which is
most accepted by them and which makes the most sense.

Example 1) We don't write JavaDoc, except when really necessary. We prefer
to write readable code. Reason: in a agile project JavaDoc gets very easily
our of sync with the source code and having a misleading JavaDoc is worse
than having none.

Example 2) As already said above, we don't prefix our variables or
parameters, because it is easier to write and looks more "aestetic" in our
eyes. Writing "m_outputStream" requires at least typing "m_o" with code
completiong. Naming it "outputStream" requires just "o" with code
completion. Also, in more than 6 years of development we never had a bug,
because a parameter was used instead of a field.

--
My 0.02¤
Tom

0
Comment actions Permalink

I think these are all good suggestions. I have one thing to say:

Example 1) We don't write JavaDoc, except when really necessary. We
prefer to write readable code. Reason: in a agile project JavaDoc gets
very easily our of sync with the source code and having a misleading
JavaDoc is worse than having none.


This might not apply to where you write code or to your development team,
but personally I have a cycle where I write a lot of code, get to a point
where it seems stable, write detailed Javadoc. Then, if I ever need to modify
any documented method, I simply click the line above with the folded /*../,
press Ctrl+X, and it's gone. Thus the Javadoc is never out of sync. When
it's stable again I re-write the Javadoc. I think this is a better system
than avoiding Javadoc.


0
Comment actions Permalink

Keith

.. I think this is a better system than avoiding Javadoc.



Comments can lie. Less comments => less possible lies.

My coding cycle is similar to yours, except that when my code is
stable, I fine-tune the names (classes', methods', variables', constants').
I also check my metaphors, and try to imagine coming back to the code
after 6 months of holiday: "do the metaphors make sense", "are the names
clear enough". That's just my way.


Alain

0
Comment actions Permalink

You can try DiamondSpin, because it has an auto code styler and I find this very helpful! You find the download version at http://www.crystalbyte.com

0
Comment actions Permalink

I think classes are one of the best java conventions.


______________
agile software development

0

Please sign in to leave a comment.