Malcolm Davis's Blog

Adapt the Java style for your own

Getting C/C++ developers to adapt new coding conventions can be frustrating to a team lead and other Java developers. Coming from a C/C++ and Microsoft background, my style was somewhat different from Sun's guidelines. I found that I was reformatting code all the time to my own convention. Reluctant to change my ways, and looking for every justification in the world not to, I asked experts for guidance. Then Bruce Eckel gave me some words of advice that are paraphrased as follows:

"..not only has Sun worked it all out (and why re-invent a good wheel), but more importantly because everyone sees the Sun code and becomes used to it -- why add the extra mental cycles necessary to shift gears every time you jump to 'your format.'"

After reading Bruce's comments, I got over my ego, and changed my coding habits. Within a few months, the Sun style had become my native convention and I had successfully re-tooled 10 years of C/C++.

While the changes might seem minor and insignificant, I had a huge increase in productivity due to Java comprehension. [It's interesting how much an ego can get in the way of being a better programmer.]

Sun's Code Conventions for the Java Programming Language can be found at http://java.sun.com/docs/codeconv/

Notes:

• The Java certification exams given by Sun use the code convention. If you plan on becoming certified, adapting to the Java style will help.
• Even though code-reformatting tools exist for every environment, code reviews go much smother if everyone is using the same standard.
• It helps with the understanding of the reference material from books, professional journals, and Java technology specifications.
• Having one global standard helps between hired developers, or developers inside a huge IT organization.

Comments

• I'll tell you why
  Why not adopt the Sun coding conventions? Simple - because they are derived from an antiquated and BAD way of coding.

  There are very good reasons why C programmers moved away from the coding styles used by Sun, and the excuse that 'modern IDEs have code colouring and brace matcing, etc.' is NOT a good reason to have to rely on it.

  Posted by: grahamtriggs on March 01, 2004 at 03:25 AM

• Obligatory link
  Here's the obligatory link to the Sun's actual conventions to aid in this discussion:

  http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html

  Code Conventions for the JavaTM Programming Language

  Posted by: trinition on March 01, 2004 at 04:47 AM

• Disagreements
  Now that the link is out of the way, here's some of the issues I have with Sun's coding conventions:

  1. They perfer to have line lengths less than 80 chars if not 70 chars. My IDE can show me approximately 150 chars on my screen, even with a vertical Windows taskbar and several small windows squishing the editor area. Why should lines only be 80 chars? Are we all still using daisy-wheel printers?

  2. Curly brace placement on lines. Sun wants code to look like this:

  try {
  if(a) {
  // A
  } else {
  // B
  }
  } catch(Exception e) {
  // ...
  } finally {
  // ...
  }

  I find it harder to cut-and-paste lines in this manner. I prefer the following style:

  try {
  if(a) {
  // A
  }
  else {
  // B
  }
  }
  catch(Exception e) {
  // ...
  }
  finally {
  // ...
  }

  It's a bit longer, but it dramatically increases my ability to select individual blocks of code for manipulation.

  3. Indentiation. Sun's direction confuses me: "Four spaces should be used as the unit of indentation. The exact construction of the indentation (spaces vs. tabs) is unspecified. Tabs must be set exactly every 8 spaces (not 4). ". If your tabs are set 8 spaces, then what good are tabs for indenting a single 4-space level? That would only be half a tab. They say the decision between spaces and tabs is unspecified, but it seems to have been set up to prefer spaces. Personally, I prefer tabs, and I indent my code such that it won't matter what your tab setting is. For example, Sun's says one of the valid ways to wrap parameters is to line up the wrapped fragment under its sibling in the previous line:

  public void foo(String a,
  String b)

  Depending on the porportionality of your font (usually monospace, but not ion this post), that may not line up right. Similarly, if I use tabs at all, it won't line up depending on your tab settings. Hence, Sun dictates 8. However, by formatting my code like this, I avoid the situation altogether:

  public void foo(
  String a,
  String b)

  Anyways, that's just a fraction of my $0.02.

  Posted by: trinition on March 01, 2004 at 04:59 AM

• tabs and curly braces??
  Good heavens, what a lightweight blog entry to show up on the java.net front page.

  Are we debating curly brace placement and indenting w/tabs? I thought the curly brace thing was long over.

  How about this: (1) curly place is irrelevant; I can read anything. (2) Indent with spaces only, not hard tabs.

  On the face of it, there's nothing wrong w/the statement "I indent w/hard tabs, so anybody can set their tab width to whatever they like". However... (a) People also tend to try to line things up *after* the first non-whitespace character on a line (e.g., line up "=" characters or comments). Variable tab widths screw that all up. Better to just use spaces, period. And (b), the default tab width on quite a lot of software is 8 space. Try "more < Foo.java" in an MS-Windows cmd prompt. Try "notepad /p Foo.java". Try "rcsdiff -r1.1 -r1.2 Foo.java". Quick: what are the cmd-line options to set tab width for 'less', 'more', 'diff', 'a2ps' and 'grep', for Gnu, AIX and HPUX? Sheesh. Better to just stick w/spaces.

  ----------------------------------------------------

  Bumping the conversation up a level, how 'bout them leading "I"s on interfaces?

  public interface IHouse;
  public interface IBoat;
  public class HouseBoat implements IHouse, IBoat;

  blech. What are your opinions?

  John.

  Posted by: johnl4 on March 01, 2004 at 05:37 AM

• Disagreements
  Regarding #1, it's not about you. It's about others who have to read/digest/modify your code. If you're doing team code reviews using hard copy, it's much more readable if formatted to Sun's specs. Also, some might prefer to use vi, emacs, etc. outside a GUI environment, and may find squeezing more than 80 characters into a text-mode line to be unreadable.

  While I also tend to write lines that go beyond the 80 char limit, I recognize that lines this long aren't really a best practice. Even ignoring the issue of printing or console-mode, it can be difficult to follow the logic of lines that are that long. In my opinion, the best practice is to break them up, rather than exceeding 80 chars or wrapping them.

  Regarding #2, I follow the same convention as you, but for a different reason. I find the added whitespace of this format to help visually associate the indented block of code with the statement that encloses it, e.g., in your example, "// A" is visually associated with "if (a) {" while "//B" is visually associated with "else {". To me this increases the readability of the code.

  For #3, I just use 4 spaces, no tabs. I've never opened a source file in anything that didn't display this correctly with no special configuration.
  

  Posted by: kdenehy on March 01, 2004 at 07:13 AM

• Disagreements
  WRT line length

  Not everyone uses your IDE -- personally, I think IDE's are a bad idea in general -- they're simply too slow.

  I use raw editor windows, and prefer to keep several visible on screen, side by side. Keeping a reasonable line length lets me keep two full size editor screens next to each other and still read the full contents of both.

  ----

  Coding styles are a fasion - there's generally little if any objective reason for most of them. Everyone has a set of preferences that they work with that impacts their style. I disagree also with the other poster that wrote something along the lines of "there's a good reason that c programmers abandoned these years ago" -- there isn't: some styles simply went out of fasion in a small community of programmers.

  When I started developing, the ideal method length was about 20-24 lines. Now, if you read the popular style guides, the ideal method length is down to about 10-12 lines. There is no objective research that can account for the change: 10-12 lines has become the new fasion. Why??? Because when I started, we had to use full screen text editors in character mode, and that was limited by the 25 lines available on a screen display. Modern IDE's are lucky to get 10-15 lines of readable text in the editor window once you've wasted screen real estate on toolbars, menus, project navigation trees and message windows.

  Posted by: david_hall on March 01, 2004 at 07:17 AM

• tabs and curly braces??
  >Bumping the conversation up a level, >how 'bout them leading "I"s on interfaces?
  >
  >public interface IHouse;
  >public interface IBoat;
  >public class HouseBoat implements >IHouse, IBoat;
  >
  >blech. What are your opinions?
  >

  Such leads to Hungarian notation, which is inherently evil (and NOT because it was adopted by (mummy, he speaks the M-word) Microsoft.

  int iNumber = 0;
  double dNumber = 0.0d;
  ISomeThing isotThing = new OTSomeThing();
  
  public class OTSomeThing extends OThing implements ISomeThing
  {
  }

  and that's just mild annoyances.
  Wait until you get classes derived 4-5 deep with 3 interface implementations...
  

  Posted by: jwenting on March 01, 2004 at 07:20 AM

• tabs and curly braces??
  My opinion is that a consesus will never be reached, and that's what makes me a bit reluctant to chime in. Fortunately, my outspokeness overruled. :)

  As far as braces, I fervently favor the brace-on-next-line style, but I know the brace-on-same-line crowd just as fervently favors that style, so I just let that issue go. I'm not likely to change their mind, and they aren't likely to change mine.

  But the 8-character tab issue...this I just can't come to understand. This effectively renders the tab key useless, so it might as well be removed from the keyboard. Who has ever wanted an an 8-character tab stop? I'll admit ignorance when it comes to the history of the 8-character tab, but I do know that it has no basis in typewriters or typewritten material, which long predate CRT-based computers, and I can't fathom any useful purpose for such a large tab. I can only imagine that it is due to some reverence for an outdated rule which was probably silly to begin with. I'd love to be corrected here, so if anybody justify this rule to me, my eyes, ears, and mind are wide open.

  Prefixes (or suffixes, for that matter) for interfaces generally make me uneasy, for they can make refactoring awkward. For instance, what today you have coded as an abstract class may tomorrow be better coded an interface, or vice versa. A naming convention ties you to a particular implementation. Plus, when you use, say, JDBC, are you conscious of the fact that the Statement you are using is really just an interface to a vendor-supplied concrete implementation class? If it has been named IStatement, the API would make you more concious of the existence of the vendor-implementation, which I see as an abstraction leak.

  Still, it's not such an easy issue, because what happens when you want a concrete House class? What do you call it? HouseImpl, a popular naming convention, is at least as ugly as IHouse. So it's hard to say.

  And there's the lesson to be learned: If you find it hard to craft a rule that fits every possible situation, stop trying. If you ever do manage to come up with such a rule, it's bound to be a round hole for at least one square peg.

  Posted by: jimothy on March 01, 2004 at 07:37 AM

• I'll tell you why
  Yes, please tell us why. You just said it's bad, not why it is bad.

  Posted by: iampivot on March 01, 2004 at 07:50 AM

• Disagreements
  Re: #1, I think 80 chars is too limiting, but I generally try to keep it down under 100 to be nice to the others who read my code. If you have to print code for inspections then 80-100 is the limit for most portait prints, and 100-120 for landscape prints. Sometimes it's just not reasonable to limit yourself strictly 80 chars max and maintain readability.

  Re: #2, I'm not sure the second example is any bettter than the first as they both are inconsistent. I find it easier to ALWAYS put a curly brace (left or right) on a new line, which takes the easy cut/paste as far as it will go. Plus, this gives you some amount of vertical pattern-matching ability when you scan code.

  Re: #3, spaces are always better than tabs, and 8 space tabs will never cut it. The inside of a 1st-level loop in a method would always start at 32 characters in! Yuck! If you're stuck with an 80-character line limit, you've lost 33% of your line. If you have 2 more levels of nesting, you've lost 50% of your line, and 40 characters is not enough to work with unless you have the shortest of names for objects and methods, and therefore completely impractical. 4 spaces (no tab) is going to be the most reasonable in all cases -- different editors that might not have definable # of spaces per tab, printing, line-limits, etc.

  I agree, your formatting works assuming long names or lists of parameters. Your example would best fit on one line, though. And I also agree that Sun's documentation is inconsistent.

  Sun's coding conventions, if followed, do not produce the most readable code, IMO. I can be flexible in some things, but Sun's standard is not useful to me. I can see why they chose it, though, as they have/had so many C/C++ programmers and it would allow them a lot of commonality.

  One of the things that I'm a big proponent of is organizing code in such a way that you can do visual pattern-matching while scrolling through the code (ie, vertical readability). This increases the speed at which you can find things in a file.

  The four biggest parts of this are: curly braces starting/ending in the same column (mentioned this earlier); using a space after opening parens, operators, names, and semi-colons and before closing parens; using blank lines to break up chunks of code into meaningful groupings (and always putting blank lines before/after if/for/while/method-class signature blocks; and (optionally) taking lists of similar statements (variable assignments or method calls), for example, and lining up the left-edges (Class object = new Class( param1, param 2) -- the objects would all line up vertically, the = would line up, the params, etc).

  Not only do these techniques speed up your reading, but (especially technique #4) because you can process them visually and quickly, you can spot errors quicker (missing parameter, missing quotes, extra characters, etc).

  Most modern editors and IDEs use syntax-highlighting with colors. UML has been proposed with colors to assign meaning. Coloring works because it takes advantage of the brain's ability to do visual processing and pattern-matching to extract meaning without actually looking at the detail (ie, reading the words and characters). If you look at a thumbnail image (say 20% of full size) of a UML model or code or whatever black & white document, it's difficult to identify what's what, especially if you haven't seen it before or not in a long time. If on the other hand you have color and have a common meaning for the colors, you can instantly deduce a number of things, or if you've seen it before, the image can trigger memory better. As they say, a picture is worth a thousand words.

  But, as I'm stating, if you don't have color (you're doing "vi" in a telnet session, or reading printed code) then you've lost a useful component of that visual processing/pattern-matchign ability unless you've organized your words and characters via white-spacing and alignment. Try it sometime, you might find you like it.

  But this argument certainly won't fly if you or your employer is focused on lines of code as a benchmark of how good your programming is (fewer or greater LOC could be valued for "tightness" or "lots of work" respectively).

  And that's my $0.05. Thoughts?

  Posted by: gerryg on March 01, 2004 at 09:21 AM

• tabs, line lengths
  why should I use short line lengths just so somebody can use vi? We could also recommend using 8.3 filenames in case somebody is using DOS. all the files should end in .jav extensions!

  spaces instead of tabs - how about just settling on a tab size, say 4? I've been doing this for years in C++ and Java and it works great. Any editor worth its salt can be configured to do this.

  The great thing about using tabs, is you can set your editor to insert the spaces instead of the tabs, and you'll never know the difference. This way if you have to be compatible with your vi friends, it is no inconvenience to you. You can use the tab key either way.

  Posted by: kenlars99 on March 01, 2004 at 10:59 AM

• History of tabs
  As I posted in a message below, I really am curious about the history of the 8-character tab. I did a bit of googling, and still haven't found an answer (other than "it's the default setting for vi," but no answer as to WHY it's the default setting).

  I've found all sorts of guidelines, such as only using tabs for indention at the beginning of lines and spaces for alignment in the middle of lines, or strictly using spaces and never hitting the tab key, or having your editor convert tabs to spaces automatically. One of my favorite edicts was, "Tabs should be 8 characters and no correspondance shall be entered into. While that's stupidly wide, at least it's a standard." All hail the standard, if if we think it's stupid!

  Here's what I want: When I hit the tab key, I want to increase the line indention by one, and only one, level. When I hit the backspace/delete key (with the cursor appropriately positioned, of course), I want to decrease the indention by one level. Not a fourth of a level, but one full level (i.e., four spaces). I paid good money for those keys, and I'll be damned if I don't get to use them!

  If some "standard" neuters either my tab or backspace/delete key, it's the standard that needs adjustment. Call it ego if you wish, but I find it interesting how much standards can get in the way of more productive programming.

  Posted by: jimothy on March 01, 2004 at 02:54 PM

• "short" lines / smart editors
  kenlars99: 80-character lines (or some other reasonable limit, like 132 :) are nice for paper printouts. Occasionally, I'll print out a bunch of code and go over it w/a pen, if I'm refactoring or adding new functionality that requires a bit of hair and touching 5 files in 21 places. Also good for code reviews. Drives me nuts when someone codes in a 250-character line just because they're running a side-scrolling editor in full-screen mode on a 21" monitor. >:(

  jimothy: there's always the possibility of getting a smart editor that's capable of intelligent autoformatting, or understanding what you mean when you hit the TAB key or the backspace key, but still using spaces to get the effect you want.

  John.

  Posted by: johnl4 on March 01, 2004 at 08:34 PM

• Disagreements
  But its not just my IDE where 80 chars is far too few. When I use an terminal window to an AIX box, myw indow is far more than 80 characters wide (helps when grepping log files). When I print, my print is far more than 80 characters wide as well. If you are still using a system that limits you to 80 characters, I'm surprised. And if so, I would think that's the minority case, not the majority -- and that minority, I would also predict, is shrinking.

  Posted by: trinition on March 02, 2004 at 04:46 AM

• tabs and curly braces??
  "a) People also tend to try to line things up *after* the first non-whitespace character on a line "

  OK, those are the people that need to be shot. That was the purpose of one of my other posts. There ARE ways to line things up using just TABS. You pick the thing you're lining up to (say, the first parameter in a parameter list) and instead of leaving it on the original line, you also bring it down a line and indent it. Then, all of your parameters are indented the same and visually grouped!

  Why was the tab created? As a shortcut for spaces? There's a character reserved for it in ASCII. As a way to save memory (1 tab char = 8 space chars)?

  There are times when I don't have as much screen space, and I'd like to switch my indent from 4 chars to 2. When you have a horrible nested chunk of code 10 levels deep, it can help to bring it into view.

  Posted by: trinition on March 02, 2004 at 04:51 AM

• I'll tell you why
  No, he did tell you why they are bad, he justd idn't elaborate. It was stated "because they are dervied from an antiquated BAD way of coding" or something like that.

  The fact is, Sun did pick many of their standards to be compatible with antiquated things, like electric typewriters that couldn't print more than 80 characters on a line. Apparently, someone at Sun still has one of these set up as their printer, so the standard had to accomodate them as the least common denominator.

  If we continue to support such ancient ways then what purpose will their be for advancement? We will never need larger monitors to display more code at once because the code will still never extend past 80 characters if Sun has its way. There would be no reaosn to because ti would break the standard and become unusable.

  OK, so I'm a bit extreme, but extremity is a useful tool in arguments.

  Posted by: trinition on March 02, 2004 at 04:59 AM

• "short" lines / smart editors
  Is it only both of the text editors I use regularly and every IDE I've ever used that supports soft line wrapping, or is it actually more prevalent?

  Posted by: trinition on March 02, 2004 at 05:00 AM

• Disagreements
  "I think IDE's are a bad idea in general -- they're simply too slow."

  I'm not trying to start a separate argument here, but... I use eclipse at home and WSAD at work. eclipse uses a lot of memory, and WSAD even more. And when it has to expand its heap (once or twice during a days work), it is very annoying.

  However, there is an INFINITE number of niceties that it has that allow me to quickly have knowledge and automate tasks without taking my hands of the keyboard. It can automatically stub a try/catch block around selected lines. It can catch compilation errors on the fly as I type. It can showme the javadoc for any suggested completion for a fragment I've typed as I'm typing it. It can properly rename a method/member syntactaically, not just as a global text search/replace.

  Yes, all of these things can be accomplished to some degree in other ways. You can use the API to find out what exceptions have to be caught and type your own try/catch block. But, seriously, when you are writing something and you know there are exceptions, hitting CTRL+ALT+T is a lot faster than having to switch to your browser to view the JavaDoc and then type the catch blocks by hand. And its not just speed for laziness. It doens't require any significant mental context switch. You just keep flowing through the same though of code you started with without interruption.

  The same holds for the rest of the niceties I listed up there, and that is the short list -- there are many more.

  I used to work with two guys who refused to use an IDE -- they used textpad.

  Once has since TRULY tried eclipse and has seen the light and now cries thinking about the time he used to wait. The other stubbornly refused to try an IDE.

  Yet he uses TextPad as a poor-man's IDE. He uses the syntax highlighting almost subconciously. When he mistypes a keyword, the highlighting won't be right, so he instictively knows he mistyped -- rather than having to go through a compile cycle to catch syntax errors. And he has other plugins and macros built that can comment lines and what not.

  Now you may have stronger reasons and greater convictions that my two friends, but when you say an IDE is "too slow", I fear your brushtroke is too broad. It can be slow to start and can consume a lot of memory -- but its all in the name of speedign YOU up so you can do what you came to do -- write code -- while it does the rest of the house keeping in such a way as to maximize your productive time and minimize your wasted time.

  Posted by: trinition on March 02, 2004 at 05:10 AM

• "short" lines / smart editors
  Doh! Touche.

  Doesn't address the paper issue, though.

  John.

  Posted by: johnl4 on March 02, 2004 at 05:12 AM

• Disagreements
  >> . If you're doing team code reviews using hard
  >> copy, it's much more readable if formatted to Sun's
  >> specs.

  Speak for yourself. Sun's standards say (IIRC) to put curly braces on the same line as the declaration, and I for one, find that format MUCH less readable than "curly-braces on a new line."

  The problem here is, there simply is not now, nor will their ever be, one standard that everybody agrees is best. Which means it's basically a waste of time to even discuss it..

  Posted by: sprhodes on March 02, 2004 at 04:02 PM

• Surprised
  I am surprised about the direction of this discussion.

  The critical issue about coding convensions is whether they help developing, maintaining and clarifying the code or not.

  IMHO consistency is the key and the ability of a team to agree to a set of rules. Where braces are put, or whether to use Hungarian or not are decisions that the team needs to make based on their situation.

  Posted by: norb on March 03, 2004 at 02:00 AM

This work is licensed under a Creative Commons License.