Java Programming Style Guide

[Anonymous]

Hi,
I'm a mainframe programmer (PL/I) that has decided to learn Java as most big companies here (the Netherlands) have started or are thinking of starting Java projects.
I saw the fantastic offer made by Paul in the Cattle Drive. The book is on order (Just Java, 2 weeks delivery).
To built up some credit :-)), here's my first posting.
Regarding the Style Guide, if I may, the following observation :
2.1 - Indention
The following :

if ( oatmeal == tasty )
{
    System.out.println("Oatmeal is good and good for you")
{
else if ( oatmeal == yak )
{
    System.out.println("oatmeal tastes like sawdust");
}
else
{
    System.out.println("tell me pleeze what is dis 'oatmeal'");
}

Would this not have been clearer :

if ( oatmeal == tasty )
{
    System.out.println("")
{
else
{
    if ( oatmeal == yak )
    {
        System.out.println("oatmeal tastes like sawdust  [img]http://www.javaranch.com/ubb/smile.gif[/img];
    }
    else
    {
        System.out.println("tell me ... oatmeal'");
    }
}

ns : I shortened the println to fit the mesg box.
Comments pse.

------------------
Marilyn added code tags.
[This message has been edited by Marilyn deQueiroz (edited January 26, 2001).]

[Jim Yingst]

The main problem I see with that style is that, if you have a long series of alternatives, you have to keep indenting for each alternative, and you march right off the right side of the screen.
<code><pre>
if ( str.equals("A"))
{
doA();
}
else
{
if ( str.equals("B"))
{
doB();
}
else
{
if ( str.equals("C"))
{
doC();
}
else
{
if ( str.equals("D"))
{
doD();
}
}
}
}
</pre></code>
vs.
<code><pre>
if ( str.equals("A"))
{
doA();
}
else if ( str.equals("B"))
{
doB();
}
else if ( str.equals("C"))
{
doC();
}
else if ( str.equals("D"))
{
doD();
}
</pre></code>
Personally, I favor the latter (as does the guide). To me it's clearer as well as more compact - but that's basically because I'm used to seeing else-ifs this way; it's a learned taste I suppose. And remember that this is with just four alternatives - the former style just gets worse and worse as more options are added, while the second stays pretty much the same.

[Peter Tran]

Jim's second version is practically an industry defacto standard way to code else if statements both in JAVA/C/C++ or any other language supporting the "else if" construct.
jdj, I thought the same as you the first time I started using else if, but I changed really quick for the reasons Jim mentioned, plus I was told to during a code review.
-Peter

[Marilyn de Queiroz]

jdj,
Please refer to http://www.javaranch.com/name.jsp and register properly so you can continue to join our discussions here at JavaRanch. Thank you.

[Johannes de Jong]

Sorry Marilyn, I've registered again as Johannes de Jong. Can you pse remove JDJ.

[Johannes de Jong]

Thanks for your reply's Jim & Peter.
If its a Java standard thats the way I'll have to do it :-))
Marilyn how did you add the code tags by the way.

[ryan burgdorfer]

Click here to see the mysteries of UBBcode unveiled... http://www.javaranch.com/ubb/ubbcode.html
~Ryan

[paul wheaton]

The style guide tries to make you hip to the industry as well as provide a consistant style. The if..else stuff you mention, as others have pointed out, is the way folks generally handle that particular situation.

[Diana Ryan]

Hi. Not trying to butt in here... I hope I'm not unwelcome on this thread.
In my own efforts to get hip to the industry standards, I picked up a book called The Elements of Java Style written by seven programmers from Rogue Wave Software (in Boulder). Consists of 108 rules, glossary and index. Very small, a quick read and a great format for reference.
I was just wondering if Paul or Marilyn had seen it, or what you thought of it. There are some inconsistencies with the guidelines here at Java Ranch. Some that I like (I think the braces style we use here is much more readable than braces that begin at the end of a line) and some that I don't like (I prefer all caps for constants). And there's stuff here that is never mentioned there, like spacing issues. And there's stuff there that isn't mentioned here, too many things to mention, but it's all very interesting.
I was wondering if Paul or Marilyn had seen The Elements of Java Style, and what you think of it.
~ Diana
P.S. I understand the title's similarity to Strunk & White's "The Elements of Style" is intentional.
[This message has been edited by Diana Ryan (edited January 28, 2001).]

[Peter Tran]

Diana,
I too have the book you mentioned. It's a good little book to see what RogueWave is doing inside their development shop. Just because they publish it, doesn't mean you have to follow it religiously. Like you said, there are things you like and don't like about some of their practices.
I think Jim word it quite nicely in this thread (see his last comment). http://www.javaranch.com/ubb/Forum19/HTML/000225.html
-Peter

[Marilyn de Queiroz]

I have not seen it, but there are lots of books on style out there and no two are alike (not to mention that lots of companies have their own unpublished style guides). Like Peter said, Jim's answer is excellent.

[Diana Ryan]

Ok. I'm still very new to coding Java (20 days), so the only Style Guides I've seen are the Java Ranch Style Guide and Rogue Wave's.
~ Diana

[Johannes de Jong]

First of all Diana, never apologize if you want to contribute to a discussion, evey persons opinion counts.
Jim's comments on which Style should be obeyed, thanks for the link Peter, says it all. "Use the style that is standard within a Project", the Style Guide posted here is the standard that is being used here.
Unless we want to waste our, and the person checking our code's, time, we need to adhere to it.
My intention in posting my opinion is to start getting involved in the forums here, heck I dont want to sent Paul 500 bucks , and to understand the reasons why that form of indention was chosen.
Both these goals have been reached and with that I want to put this topic to rest.
My thanks to all that contributed.
Jim, Peter, Marilyn (did you remove JDJ, sorry again), Ryan (thanks I'll start using UBBCODE), Paul (man as mainframe programmer to be hip again, cherish the thought) and off course Diane (good luck with you Java)

JdJ <- sorry Marilyn I'm very fond of this one, it was my first userid back in 1977 when it all started for me.

[paul wheaton]

To add a touch of frosting to Jim's comment:
Someday you might be a $400 per hour Java contractor. You bounce around from company to company. If you use the existing style guide without complaint, your client loves you and you have a good chance of having your contract extended and maybe being invited back for another project. If you mention "an obvious flaw" with the style guide, you might find your contract cut short.
Style guide's border on religious debate. Chances are that any standing style guide came to be after long, bloody battles. Questioning any style guide is bound to piss off somebody. Chances are that a majority vote made that change in the style guide ....
The style guide serves two purposes for the cattle drive. To learn some elements of common style and to make things easier for the nitpickers by being more consistant.
90% of this style guide is what you will find in a majority of code and a majority of other style guides.

[Johannes de Jong]

Hope I did not piss of the sheriff or any of his deputies here

[paul wheaton]

Nope. I encourage this sort of thing. If you look back through all of the old messages, you will find quite a few discussions on the style guide. One time, a discussion here ended up in changing the style guide.

[Johannes de Jong]

Thats good news Paul.
As a matter of interest do you know that I have never seen a programming style document at any of the companies I have worked at (mostly IBM mainframe shops). Sure they sort of look at your code and bitch about the names you use, but as far as indention etc. goes no way.
I must say I am pleasantly suprised that you "PC-boys" are so professional.
My current task is to extract information out of the modules that are changed within our production environment, which files they use, what other modules they call, that sort of stuff. The programs here are written in PLI or Cobol.
Man what I would have given for a style guide for these two languages.
For Cobol I have given up extracting the information out of the source. I go directly to the objects and excecutables (we call them loads). Real nice programming at BIT-LEVEL
For PLI (or PL/1 IBM isnt even sure ), I still use the source but heck I'm close to an heart attack.
Once Java is implemented here I might have to extract that kind of information from these programs as well. They are busy with pilot sites using IBM's VisualAge for Java. As far as I know there is no Style Guide, I suppose they will use the standard that VisualAge generates. (???)
Or they wont bother again

[This message has been edited by Johannes de Jong (edited January 31, 2001).]

[paul wheaton]

The cattle drive process is basically a code review. And you cannot do a decent code review without a style guide.
More and more companies are recognizing the value of the code review (or going extreme with pair programming) and are adopting a style (like ours) or taking a style and modifying it slightly to meet their needs, or what they think a style guide should be. I know several companies have done this with our style guide.

[Johannes de Jong]

Originally posted by Paul Wheaton:
The cattle drive process is basically a code review.

Which brings me to the following question, what do people like yourself get from putting so much time and effort into the JavaRanch.

[This message has been edited by Johannes de Jong (edited January 31, 2001).]

[Marilyn de Queiroz]

>Marilyn (did you remove JDJ, sorry again)

It has been inactivated.

[Johannes de Jong]

Thanks Marilyn, my first assignment will be tackled this weekend, looking forward to your "nitpicking"

[paul wheaton]

Well,
We get panick attacks when we see a big assignment in our e-mail.
We get hate mail and people who tell us what jerks we are.
We get people who tell us our methods are all wrong - usually this is before they have tried the methods.
But we also get people who feel they learned more with this than anything else. And we get people who hang around the saloon and help others. Some of the drive folks move up to be bartenders, or contribute to the ranch in other ways.

[Johannes de Jong]

We get panick attacks when we see a big assignment in our e-mail.
I bet
We get hate mail and people who tell us what jerks we are.
Why if you only want to help.
We get people who tell us our methods are all wrong - usually this is before they have tried the methods.
I promise I will try them before I critisize (if I do )
But we also get people who feel they learned more with this than anything else. And we get people who hang around the saloon and help others. Some of the drive folks move up to be bartenders, or contribute to the ranch in other ways.
That's why I'm here to learn and hopefully one day contribute as well. I like your way of teaching by the way
[This message has been edited by Johannes de Jong (edited February 01, 2001).]
[This message has been edited by Johannes de Jong (edited February 01, 2001).]

[Joseph Russell]

I just thought I'd say how much I appreciate all the work that goes into JavaRanch. It's so far been the best learning tool I've come across. you guys are cool
Joe

[paul wheaton]

Originally posted by Johannes de Jong:
We get hate mail and people who tell us what jerks we are.
Why if you only want to help.

I suspect it is because we say "your code sucks!" and they don't agree.

[Johannes de Jong]

Hey only an idiot cant appreciate constructive critism.
But Paul you still havent answered my question as to why you all do this. I know not all or motivated by money but what motivates the average Bartender around here. Why would the average greenhorn want to work his way up to becomeranch hand, bartender etc.

[Marilyn de Queiroz]

You don't have to do much to become a ranch hand. Just post. When you reach 31 posts, you are automatically promoted.

People who try to help others, who like this site and want to help it succeed/improve usually eventually are nominated to become bartenders.

[Joseph Russell]

It's also good for beginners to see and learn from others mistakes or to even be able to help them out.

[Anonymous]

I've just started using this forum and noticed the stuff at the top of this about using your proper name - sorry, I'll change mine.

[Pres Brawner]

I too, see value in the style guide. There are some interesting oddities in the one used here. It is non-standard. It doesn't match the one used by the recommended text (Just Java), nor does it match the style used by Sun, nor does it match the style guides followed in any of the publications that I read (Java Journal, Dr. Dobbs Journal, Web Techniques).
My experience was that everything that I had been doing, and that looked "natural" to me had to be discarded. I could not code like I did at work. I had to examine every space, brace, and paren. I still make lots of these errors. I hate the style guide every time I try to complete an assignment, but it does force me to consider style as a separate, arbitrary, unnatural force that has to be dealt with.
It would be very helpful if those reviewing the assignments would do something that would differentiate style corrections from logic corrections.
(and please don't use "!" in your comments. I was told "Don't include an explanation point in writing unless you would shout at the person for whom the sentance is intended". Maybe the commenters really would be shouting at me. There's an unnerving thought!

[JC Cook]

I was told "Don't include an explanation [sic] point in writing unless you would shout at the person for whom the sentance [sic] is intended".

Well, I was told that opinions are like noses -- everybody has one. In this case, Webster's New World Dictionary defines exclamation mark as "a mark (!) used in punctuating to show surprise, strong emotion, etc." So assume no one is shouting, just emphasizing.

[Marilyn de Queiroz]

There are lots of style guides. None of them are the same. The code that I've seen in print that is the most similar to this style is in a textbook by H.M. Deitel & P.J. Deitel called Java � How to Program.
[This message has been edited by Marilyn deQueiroz (edited February 19, 2001).]

[Marilyn de Queiroz]

Originally posted by Pres Brawner:
It would be very helpful if those reviewing the assignments would do something that would differentiate style corrections from logic corrections.

Do you have a suggestion about how to implement this?

[Pres Brawner]

To differentiate between style and logic might involve several different options.
Caps vs lower case
Standard font versus italics
color red versus color green
Any of these things might work. Some might require html email.

[Pres Brawner]

I appologize if voicing my opinion offends JC.
I've been told to post or face a $500 fine.

[Marilyn de Queiroz]

Some people don't have html email and html code shows up as garbage characters in their email.

Capitalization might work, but most people consider words in all caps as being shouted (worse than exclamation marks).

Any other ideas?

[JC Cook]

No offense taken, Pres. And none intended in my reply.

[ryan burgdorfer]

Style-specific comments could simply begin with the word STYLE (in caps), like so:

some code
{
    ...
    blah blah
)
STYLE: spacing...

Other (logical/syntactical/etc.) comments could just remain as they have been, not beginning with STYLE: ...
~Ryan

[Johannes de Jong]

Not a bad suggestion at all Ryan , I as a Cattle Driver that will still get a LOT of nitpicking coming my way can life with that suggestion

[Pres Brawner]

Of the approaches that I mentioned at least the caps no caps would work regardless of whether the reader gets html email or not.
Granted, some people don't get html email in this world, but developers? We are not representative of the population at large. It would be worth sending a sample email to the readers. I think that nearly all would be able to detect html email.
Other conventions might include:
<style>spacing</style>
<logic>you have selected a non optimal algorithm - look up "bubble sort" in your favorite CS textbook</logic>
No html code required there. If there's a will, there are many ways.