Please, only people with actual paid experience answer this question: I'm beginning my 'career' in Java and want to learn it correctly from the start. That included picking up the correct coding standards that will help my code be easy to maintain and understand. I've read the 'CattleDrive' coding standards and have implemented them for the most part. However, my programs are beginning to become REALLY 'airy' - LOTS of spaces all over the place. It's actually getting a little difficult to read and understand the flow. So, my question is this: What code below is more 'realistic' - as in, when I start to actually work, what will more people want to see? THE MORE POSTS THE BETTER as this is an opinion poll!!
Here is another way to do it:
Obviously, the biggest difference is that the 'one liners' go on the same line, making it REALLY easy to pick out what's going on where. Also, once in awhile in algorithms, I'll NOT put spaces around array indexes or conditional tests - it's actually easier to read:
Maybe the getNumber() isn't the best example, but it doesn't take long for the spaces and everything to start pushing text onto the next line and making it really ugly/airy. OPINIONS BASED ON REAL EXPERIENCE, PLEASE!! Thanks all!
-nothing important to say, but learnin' plenty-
Joined: Feb 05, 2003
Admin - Could you maybe move this to Intermediate if it would be better answered there? Thanks....
Things like which coding/naming standards to follow are decided right at the start of a project. That said, coding standards can be briefly categorized into 1) naming conventions to be used (package, class, variable names, etc.) 2) indentation (where to put curly braces, whether to use tabs or space, etc.) The naming conventions can be either standard ones (from SUN) or custom developed ones. The indentation is usually the default that the IDE provides.
Keeping in mind that your code must be read by people other than yourself, readability is important. So in other words the code should be nicely formatted according to some standard to facilitate readability, which in many cases means some amount of white space will be introduced. There is no reason to try to cram as much code on one line as possible, as it makes it more difficult to read. Given the first two examples you offered, the first one is closest to what I see on the job. The truth is though that most of the Java code I look at generally follows the Code Conventions for the JavaTM Programming Language. That doesn't mean that there is anything wrong with the CattleDrive standards, and in fact you may find different coding conventions in different shops throughout your career. If I had done the same code you gave, it would look something like this.
Joined: Feb 05, 2003
Jason: Did you hand type all the comments and necessary /**, etc.? I was wondering if there are shortcut keys in various IDE's (I use JDeveloper) to insert the various comment characters to speed up typing a bit...I had no idea that code could be so commented...at first it is harder to read (because the comments break up the flow), but I guess in the end it's much better to be able to understand what the coder was thinking and why...thank you...
Most IDEs do indeed help you put those comments in, in various ways. I agree with the points that have been made so far: each shop will have its own coding standard, and you have to go along with it; for most shops, it's the Sun one. Virtually all coding standards will prohibit the method-all-on-one-line version, and pointing this out is the main reason I'm posting on this thread!
there are also tools that make some parts of coding styles less important... when you check code out of your source control, you may get it formatted one way. then, you run it through a tool, wich would reformat it to how you prefer to see it. you use your editor, making changes in the style you are comfortable with. then, before checking it back in, you'd reformat it back to the "standard" way. of course, this doesn't effect method names, packages, etc. but it makes the religious argument about curly brace placement irrelavent. Unfortunatly, i don't think the tools we've looked at can do it the way my company has declared the standard. I'm not sure if this says more about the weakness of the tool or the crazy standard we have adopted...
There are only two hard things in computer science: cache invalidation, naming things, and off-by-one errors
Joined: Nov 09, 2000
Originally posted by David Crossett: Jason: Did you hand type all the comments and necessary /**, etc.? I was wondering if there are shortcut keys in various IDE's (I use JDeveloper) to insert the various comment characters to speed up typing a bit...I had no idea that code could be so commented...at first it is harder to read (because the comments break up the flow), but I guess in the end it's much better to be able to understand what the coder was thinking and why...thank you...
In the code that I presented above, I hand typed it (a lot of cut and paste actually). As Ernest stated though, most IDE's have something to help with commenting. I use JBuilder 9 Enterprise on the job, and it does very well with commenting and generating JavaDocs. For some more information, I would direct you to "How to Write Doc Comments for the JavadocTM Tool".
Our team used Elements of Java Style by Ambler & others as a starting point (bought a copy for every team member) and made up a very short list of exceptions. The main exception I push for is aligning curly braces - this is personal but I hate K&R brace style. I use the code formatter in my IDE about as often as I save or compile. It gives a very consistent style, even if it's not what I'd choose on my own. Frinstance, I like one-line getters & setters but I live with multi-lines because the current formatters insists. Re JavaDoc ... if a method needs doc, consider it an opportunity to improve the names and structures until the code explains itself. I put more effort into package and class doc and try hard to not need method doc.
A good question is never answered. It is not a bolt to be tightened into place but a seed to be planted and to bear more seed toward the hope of greening the landscape of the idea. John Ciardi
Joined: Nov 09, 2000
Originally posted by Stan James: Re JavaDoc ... if a method needs doc, consider it an opportunity to improve the names and structures until the code explains itself. I put more effort into package and class doc and try hard to not need method doc.
This isn't a developer option in many cases. The coding standards of many shops dictate what will be commented, typically including packages, classes, and public and protected methods.
I think most people use Jason's style, the so-called Sun style. It is less "airy" and still very readable. The other big advantage is that if you ever take the Sun developer certification it's the style you really, really should use then.
Spot false dilemmas now, ask me how!
(If you're not on the edge, you're taking up too much room.)
[Stan]: if a method needs doc, consider it an opportunity to improve the names and structures until the code explains itself. [Jason]: This isn't a developer option in many cases. Sad but true. Some shops expect comments on private members too, which can be really annoying, IMO. I often extract a block of code into a private method (with a nice decriptive name) to improve readability. But if that means I also have to spend extra time on comments for the new method, I might prefer to just leave the code where it is. But at least if you've organized the code well and chosen good names, the comments can often be fairly minimal. Like Stan, I usually prefer to spend more time on the class and package comments; many methods are fairly obvious from their names. Some aren't, of course, and those certainly deserve detailed comments too.
"I'm not back." - Bill Harding, Twister
subject: I need experienced replies only regarding coding standards!