Personal Practices

Add your list of the 5 best rules of thumb for writing Java.

Former user (Deleted) (Rutgers)

My personal thoughts, surprisingly not all that Java-centric:

1. Commit early, commit often – though never check in anything that someone else hasn't at least done a "hallway check" (these checks work surprisingly well in bug-tracing too – go ask someone to look at your problem at which point the source will often become obvious )
2. Never, ever eat exceptions. At least log that something bad has happened. In most cases you should really probably either throw it, or wrap it in a RuntimeException and then throw it, and implement an "Exception Barrier" approach to error handling
3. Automate ruthlessly. Especially related to building or deployment. Even if you're only going to do it once
4. Always Google to see if an open-source library has already solved your problem before you write code.
5. Do your documentation (javadocs, unit/acceptance tests, install notes, issue tracker) when you do the work – putting it off until later is a good way to make sure it doesn't get done

Peter Crowther

These are all "micro" heuristics; I've no doubt others will give the high-level ones!

1) Pseudocode complex algorithms in comments, in English, at a high level. Then fill in the code, retaining the comments as a high-level description of what the code is doing.

2) Other than the above, which I only use for complex algorithms, comment why not how. "Add 1 to array base" is not a useful comment. "The input array is 1-based (see the param comment), hence starting the loop at 1" is. (The example's from some statistical software I'm working on, which used 1-based arrays because much of it's translated from Fortran).

3) Use meaningful variables, with the shortest possible lifetimes and most local possible scopes; do not re-use a variable for a different purpose "because it is there". This makes it far easier to track down the places a variable may be used or changed.

4) Adhere to formatting and naming conventions. Yes, we know all programmers have egos, and your personal style is much better than anyone else's. Use the standard anyway, and never, ever, reformat code away from that standard. Everyone will thank you when they're merging patches in.

5) Buy, read and mull over Steve McConnell, "Code Complete, 2nd Edition", Microsoft Press. You won't agree with everything in it. You won't like some of the things that are in it, because they will attack your ego as a creative programmer. Reading and deciding why you don't like particular pieces of advice will make you far more aware of code, and you'll very rapidly recoup the time you spent reading it.

• Peter

Former user (Deleted) (Unicon, Inc.)

1. never swallow exceptions
   You'll see this repeated a lot. But anyone who has ever had to maintain code where this anti-pattern is encountered, will know why this is enemy number one.
2. program to interfaces
   If you program to interfaces lots of good things happen. This is true even when you only have one implementation. For one thing it enables Spring AOP proxies. It helps with class loader issues. It encourages better modular programming.
3. Use generics
   This is a new one for me. And I understand the hestitancy to adopt new technology/libraries in code that's been around. But in the case of generics, it's really hard for code that comes later to be 'coded right' if the libraries it calls aren't coded with generics. However the reverse is not true. A library coded with generics, puts no requirement on the code that uses it, to use generics.
4. synchronize sparingly
   It is not correct to say "never synchronize" your code. It's also not correct to say "always synchronize" your code. Thread synchronization is one of those things that is really hard to get right. My only advice here is, do not take either extreme. If you take either extreme, I can just about guarantee you'll be wrong in some setting.
5. Follow the practices and coding styles in the code you're editing
   This one is hard, given that there is a lot of bad code out there. But, I will stick by this lesson taugh to me over 10 years ago. Do not go into code and say "man, this is all wrong" and reformat/recode it to what you think is the best practice. This goes for both coding style (spaces, tabs, indentation, brackets, variable names, etc) and 'best practices'. Now there's a risk here. Some practices, like #1 above, are just not negotiable. Other practices though are different. I disagree with certain variable naming conventions I've seen. However if I edit a file that follows one of those conventions, then I believe I should follow it as well. Having a file that has two different coding patterns in it, is harder to follow then one file that has a pattern you don't agree with.

Ray Davis (UC Berkeley)

All these guidelines derive from the sad realization that I'm not omnipotent, omniscient, and immortal. I started accumulating them back when relational databases were an exciting buzzword, but most of them have Java-specific implications.

1. Begin by extracting the slimmest useful front-to-back functionality and implementing it, putting placeholder comments in as needed. Test, commit, and layer fuller functionality in increments. This maximizes opportunities for programmer / user-rep collaboration, reduces feature padding, minimizes the chance that when my work is "interrupted" (and it will be) I'll have nothing to show for it, and gives everyone a nice warm feeling of progress.
2. Make the source as readable as possible: meaningful class names, self-descriptive variable names, no "clever" solution left uncommented, no clashing conventions, no unnecessary duplication of logic that's already publicly available under another name. When code starts to get foggy or long-winded, refactor. Always look for new ways to simplify – the Spring crew have been very helpful in that regard.
3. Don't prematurely generalize. Stick to what I need at the moment until I'm about to copy and paste. Now that I have enough evidence to understand what generalizations would be useful, refactor. Similarly, wait to design public interfaces until I have a customer to talk to.
4. Although I've never done all-out test-driven development, it would be crazy to write or change a complex or externally visible service without putting automated tests in place. That means making sure automated tests are possible.
5. Have other brains check my work somehow. If I'm not lucky enough to work on a cross-functional team, ask a co-worker to try out the user interaction. If I'm not lucky enough to get real code review, try to rotate who's working on what modules. In Sakai, at the very least get a JIRA task (or equivalent) to support discussion.

Add your name here