Style

1. Style

2. About the book • This book is a team effort by many good programmers, not just one person’s opinions • The rules have been widely distributed and commented upon • The rules reflect widespread and accepted practices • And no, I don’t agree with everything in the book!

3. Rule 1: Adhere to the style of the original • Consistent style is very important • Most times, you will enter an ongoing project, with established style rules • Follow them even if you don’t like them • Don’t try to establish “better” style rules • It won’t work anyway • There may be reasons you don’t know about • If a project has mixed styles with no consistency, you might try to get people to agree on one

4. Rule 3: Do it right the first time • You’re working on a large project, so you use good style... • ...but you need a tool to help you do one little job, so you slap it together quickly • Guess which program will be around longer and used by more people?

5. Rule 5: Indent nested code • Always indent statements that are nested inside (under the control of) another statement • if (itemCost <= bankBalance) { writeCheck(itemCost); bankBalance = bankBalance - itemCost;} • while (seconds > 0) { System.out.print(seconds + "..."); seconds = seconds - 1;} • Indentation should be consistent throughout the program • 4 spaces has become more-or-less standard

6. Rule 6: Break up long lines • Scrolling a window horizontally is a pain! • When you print on standard paper, long lines are either cut off or wrap in bad places • I have long used a 72 character limit • Some editors will show you a limit line • Various suggestions: • Break after, not before, operators • Line up parameters to a method • Don’t indent the second line of a control statement so that it lines up with the statements being controlled

7. Rule 8: Don’t use “hard” tabs • Once upon a time, you could depend on tab stops every eight character positions • Today, every editor has its own idea of where and how to set tab stops • If you change editors, your nice indentation gets ruined • It’s worse if you use both tabs and spaces • I have learned this one the hard way! • A hard tab is an actual tab character in your text • Good editors can be set to use soft tabs (your tab characters are replaced with spaces) • BlueJ uses only soft tabs; Eclipse can do either

8. Rule 9:Use meaningful names • Names should be chosen very carefully, to indicate the purpose of a variable or method • If the purpose changes, the variable or method should be renamed • It is worthwhile spending a little time choosing the best name • Long, multiword names are common in Java • Eclipse makes it very easy to rename things

9. Rule 10: Use familiar names • Where common terminology exists, use it; don’t make up your own • Example from the book: If your users refer to “customers,” your program should use the name Customer, not Client

10. Rule 11: Question excessivelylong names • Variables should be used for a single purpose • Methods should do one simple, clearly defined thing • If a descriptive name is overly long, maybe the variable or method is trying to serve too many purposes

11. Meaningful names: exceptions I • It is common practice to useias the index of a for-loop,jas the index of an inner loop, and k as the index of a third-level loop • This is almost always better than trying to come up with a meaningful name • Example: • for (int i = 1; i <= 10; i++) { for (int j = 1, j <= 10; j++) { System.out.println(" " + (i * j)); }}

12. Meaningful names: exceptions II • Method variables may be given short, simple names, if: • The purpose of the variable is obvious from context, and • The variable is used only briefly, in a small part of the program • But never use meaningless names for fields (class or instance variables)

13. Rule 28: Use standard names for “throwaway” variables • If variables have no special meaning, you can use names that reflect their types • For example, if you are writing a general method to work with any strings, you might name them string1, string2, etc. • Alternatively, you can use very short names • s,t, u, or s1, s2, etc. are often used for Strings • p, q, r, s are often used for booleans • w, x, y, z are often used for real numbers

14. Rule 12: Join the “vowel generation” • In more primitive languages, names were often limited to 8 or so characters • This led to names like maxVolum and lngPlyng • The usual rule was to leave out vowels, starting from the right • Such names are harder to read and to remember • Do not leave out vowels, or otherwise use unusual abbreviations, in Java!

15. Naming classes and interfaces • Rule 18: Capitalize the first letter of each word, including the first:PrintStream, Person, ExemptEmployee • Rule 19: Use nouns to name classes:ExemptEmployee, CustomerAccount • Classes are supposed to represent things • Rule 20: Use adjectives to name interfaces:Comparable, Printable • Interfaces are supposed to represent features

16. Naming variables • Rule 25: Capitalize the first letter of each word except the first:total, maxValue • Rule 26: Use nouns to name variables:balance, outputLine • Variables are supposed to represent values

17. Naming methods • Rule 22: Capitalize the first letter of each word except the first:display, displayImage • Methods are capitalized the same as variables • Rule 23: Use verbs when naming methods:displayImage, computeBalance • Methods are supposed to do something

18. Rule 13: Capitalize only the first letter in acronyms • In names, write acronyms such as GUI and API as Gui and Api • Examples:setDstOffset,, displayAsHtml,, loadXmlDocument • Since capital letters are used to separate names, this rule helps avoid confusion • Sun’s APIs don’t always follow this convention

19. Naming constants • A constant is an identifier whose value, once given, cannot be changed • Constants are written with the keyword final, for example: • final int FIVE = 5; • final float AVOGADROS_NUMBER = 6.022E23; • Rule 31: Constants are written in ALL_CAPITALS, with underscores between words • Exception: color names, such as Color.pink • Colors were defined before conventions were established • However, Java 1.4 adds properly capitalized names for colors, such as Color.PINK

20. Kinds of comments • “Standard” (C-style) comments: /* ... */ • One-line and end-line comments:// a one-line comment is on a line by itselfx = 0; // an end-line comment follows code • All of the above are “internal” comments, seen only by someone looking at your code • Don’t overcomment; not every line needs a comment! • Internal comments are only for maintainers • But avoid things that would embarrass you to a user! • Documentation (javadoc) comments: /** ... */ • These are meant to be seen by the entire world! • Documentation comments are not covered in this series of slides

21. Which kind of internal comment? • Rule 36:Use “standard” (/*...*/) comments to comment out code without removing it. • However, this assumes you are using a simple text editor, because it saves typing // over and over again • This is a bad rule if you are using a decent IDE • Standard comments cannot be nested, so it’s tricky commenting out code with comments • One-line comments don’t have this problem • Both BlueJ and Eclipse make it very easy to use one-line (//...) comments

22. Explaining the code I • Rule 59: Add internal comments only if they will aid in understanding your code. • Don’t repeat the javadoc comments • Don’t put in comments to explain things that are obvious from the code • Don’t put in irrelevant or useless comments • // Go Red Sox!!!! • Always put /* ... */ comments before the code they describe, never after the code

23. Explaining the code II • Rule 37: Use one-line comments to explain implementation details. • One-line comments are also good for writing reminders for yourself about things you still need to work on • // These assertions should be replaced by Exceptions • I like to use one-line comments to tell what the next several lines of code are going to do • // Put this Vehicle in a random location

24. End-line comments I • Rule 62: Explain local variable declarations with an end-line comment. • int edgeDistance; // distance to the nearest edge • But don’t let your lines get too long • And Rule 64 says: Label closing braces in highly nested control structures. • } // end switch } // end if } // end for j} // end for i • Better yet, avoid highly nested control structures

25. End-line comments II • I also find end-line comments useful for an else that is a long way from its if: • if (distance > 5) { ... a lot of code in between ...}else { // distance <= 5...} • But now that we have assert statements, this is even better: • ...else { assert distance <= 5;...}

26. Flagging unresolved issues • Rule 63: Establish and use a set of keywords to flag unresolved issues. • Eclipse uses these three (you can add more): • TODO for things you would like to do in the future • FIXME for things which are broken and you need to fix, but you aren’t working on at the moment • XXX for things that are arguably broken and you need to think about some more before you do anything

27. Intentionally missing break • Rule 65: Add a “fall-through” comment between two caselabels of aswitchstatement, if nobreakstatement separates those labels. • The switch statement is so badly designed that forgetting the break is a common error • To keep an intentionally missing break from being “corrected,” add a comment

28. Label empty statements • Sometimes you intentionally use a loop with an empty statement body • Rule 66: Label empty statements. • while ((c = reader.read()) == space) ;// Empty body • This is because the semicolon is small and easy to overlook • I prefer a different solution: use an empty block as the statement body • while ((c = reader.read()) == space) { }

29. Don’t repeat the code • Rule 60: Describe why the code is doing what it does, not what the code is doing. • Another way of saying this is:Comments should not echo code. • Here’s a typical example of a bad comment: • count = 0;// set count to zero • You should assume that anyone reading your internal comments knows some Java!

30. Use the active voice • Rule 34: Use the active voice, and omit needless words • // zero out the array • // each of the elements of the array is set to// zero by the following loop • Writing comments is still writing--all the rules for good writing apply to comments • Best reference: The Elements of Style, by Strunk and White

31. Debugging statements • We sometimes put in debugging statements that we plan to remove afterwards • Simple trick: start these “temporary” statements in the first column, so you can find them easily • boolean legalLocation(int row, int col) {System.out.println("In legalLocation: " + row + " " + col); return row >= 0 && row < numRows && column >= 0 && column < numCols; } • Another option: • final boolean debugging = true;...if (debugging) System.out.println(...)

32. The End

33. The End