[EBOB-DISCUSS] coding style

[Liam M. <lm...@wp...>]

Looking at the Prop-Ed wiki page reminded me of something... coding 
style. It's probably good to be consistent. I suggest using the Java 
Built-in style, as far as code formatting goes. I'm sure other issues 
will come up.. I'd like to see a document get added to the Docs page on 
SF. Here are a few ideas, some of which are copied/pasted from Kevin's 
coding guidelines page (some of which I have a different opinion on)... 
some of them are really basic and common sense, others are good habits 
i've been taught, still others boil down to personal opinion. If all of 
this sounds good, then great- if some of this sounds bad or if there's 
something missing, then reply. If you don't think there needs to be a 
official document that decrees our coding style, that's cool too.



Eclipse has a lot of default code templates that mention something like 
"To change this, please go to Window > Preferences > Java > Code Style > 
Code Templates". I can't remember what they say exactly because I 
already got rid of that part... I think one of the files I checked in 
still has it. We should probably remove that from our code templates.

I'll have to check whether or not the Eclipse license needs to be 
included with the sourcecode... a lot of people throw the license (or a 
disclaimer, which is scary) at the top of each source file. That'd be 
easy if we wanted to do that, or if we wanted to have something else.

*Meaningful* javadoc is important. The question is, what gets javadoc? 
Public only methods/fields? or private methods too? What about private 
fields?

I'd say we can probably safely settle on java 1.4 as a target jvm to 
shoot for; we can probably avoid using new java 1.5 code.

As far as code suggestions go:
If possible, use an interface as a return type rather than the class 
that actually implements the interface. What I mean by this is, let's 
say your method returns an ArrayList. If possible, you want to return a 
Collection object instead, or if you need to return specific list 
functionality then return the List. No casting is necessary, just 
specify "Collection" or "List" as the return type and you're set.

As far as using arrays vs. the Collection heirarchy goes... I always 
thought it's best to use arrays when dealing with data that has a fixed 
count, and collections when dealing with things that change size. Some 
people say to always use Collection, but I think that there's some 
unnecessary overhead. Arrays are often more concise/readable when it 
comes to for loops etc (that is, before java 1.5).

If you're using a Collection and you're not sure which implementation to 
go with, when in doubt, use ArrayList. It's faster.

When accessing a Collection that implements the "java.util.RandomAccess" 
interface (like ArrayList, Stack, or Vector),  use this:

for (int i=0, n=list.size(); i < n; i++)
         list.get(i);

instead of this:

for (Iterator i=list.iterator(); i.hasNext(); )
         i.next();

It's faster. (The javadoc page for RandomAccess explains it better.) 
Consequently when using something that doesn't implement RandomAccess, 
use an iterator. (Or if you need to traverse a list in either direction 
or add/remove from a list while traversing it, use ListIterator, but 
only if you have to.)

Some people say to return Iterators instead of Collections. I prefer to 
return collections (rendered unmodifiable using the Collections utility 
class if this makes sense) because you can only use an Iterator once, 
and it doesn't support random access.

Use the final modifier when possible.

Try not to use the ?: ternary operator, unless it makes MORE sense than 
using if/else and it's really brief.

When choosing between code conciseness and clarity, go for clarity.

Use common sense when it comes to using braces on one-line statements. 
If the statement's easier to read without the clutter, leave it out; if 
it's easier to read with the structure, leave it in.

Last but not least, don't break the build.;) Comments?

Liam