style l.
Download
Skip this Video
Loading SlideShow in 5 Seconds..
Style PowerPoint Presentation
Download Presentation
Style

Loading in 2 Seconds...

play fullscreen
1 / 33

Style - PowerPoint PPT Presentation


  • 122 Views
  • Uploaded on

Style. 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!.

loader
I am the owner, or an agent authorized to act on behalf of the owner, of the copyrighted work described.
capcha
Download Presentation

PowerPoint Slideshow about 'Style' - xantara


An Image/Link below is provided (as is) to download presentation

Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author.While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server.


- - - - - - - - - - - - - - - - - - - - - - - - - - E N D - - - - - - - - - - - - - - - - - - - - - - - - - -
Presentation Transcript
about the book
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!
rule 1 adhere to the style of the original
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
rule 3 do it right the first time
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?
rule 5 indent nested code
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
rule 6 break up long lines
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
rule 8 don t use hard tabs
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
rule 9 use meaningful names
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
rule 10 use familiar names
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
rule 11 question excessively long names
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
meaningful names exceptions i
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)); }}
meaningful names exceptions ii
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)
rule 28 use standard names for throwaway variables
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
rule 12 join the vowel generation
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!
naming classes and interfaces
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
naming variables
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
naming methods
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
rule 13 capitalize only the first letter in acronyms
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
naming constants
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
kinds of comments
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
which kind of internal comment
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
explaining the code i
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
explaining the code ii
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
end line comments i
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
end line comments ii
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;...}
flagging unresolved issues
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
intentionally missing break
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
label empty statements
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) { }
don t repeat the code
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!
use the active voice
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
debugging statements
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(...)