Style Jan 14 2019 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 2 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 3 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 4 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 5 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 6 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 7 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 8 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 9 Rule 11 Question excessively long 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 10 Meaningful names exceptions I It is common practice to use i as the index of a forloop j as 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 11 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 12 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 13 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 14 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 15 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 16 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 17 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 18 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 19 Kinds of comments Standard C style comments One line and end line comments a one line comment is on a line by itself x 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 20 Which kind of internal comment Rule 36 Use standard comments to comment out code without removing it However this assumes you are using
View Full Document
Unlocking...