RE: [EBOB-DISCUSS] coding style

[Gary P. <gpo...@co...>]

Well, a simple thing is to make your environment preferences have the style
you want, then export them to a .epf file. Then put it in the project for
other people to import into their eclipse workspace for the project.

	--Gary 

-----Original Message-----
From: ebo...@li...
[mailto:ebo...@li...] On Behalf Of Liam
Morley
Sent: Saturday, November 13, 2004 3:16 AM
To: ebo...@li...
Subject: [EBOB-DISCUSS] coding style

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



-------------------------------------------------------
This SF.Net email is sponsored by: InterSystems CACHE FREE OODBMS DOWNLOAD -
A multidimensional database that combines robust object and relational
technologies, making it a perfect match for Java, C++,COM, XML, ODBC and
JDBC. www.intersystems.com/match8
_______________________________________________
Ebob-discussion mailing list
Ebo...@li...
https://lists.sourceforge.net/lists/listinfo/ebob-discussion