From: Liam M. <lm...@wp...> - 2004-11-13 08:16:18
|
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 |