JAVA编程风格.doc

The Definitive CS106 Style GuideTable of Contents:Why Should I Care about Style?Good NamingCommentingDecompositionWhitespaceInstance vs. Local VariablesElegant Code StructureAlways Use Constants:General and Reusable Methods:There Are Many Ways To Solve the Same Problem:Short Methods:Why Should I Care about Style?It's common when you're writing code to think it's self- explanatory. However, for anyone (yourself included) who's seeing code either for the first time or for the first time in a few days, the way the code works isn't always immediately obvious. The reason good style is important is because well-structured, easy-to-read code is easier to modify, easier to debug and easier to work with. This is something that will save you hours of work.When in doubt as to whether you should do something for style reasons ("should I comment this line?"), just remember the spirit of code style: the object is to make your code as readable as possible. Here are some tips to make your programming style better and the life of anyone reading it much easier!Good NamingUse meaningful names, but don't go overboard. Suppose you have a variable in your program that holds the number of hours employees worked in a week:/*OK, but not very descriptive*/int hours = 40;/*much more descriptive, but cumbersome*/int hoursTheWorkersWorkedInOneWeek = 40;/*a good compromise*/int hoursPerWeek = 40;Common abbreviations are often acceptable in variable names, like hrsPerWeek. But don't get carried away; hrsPWk simply is not a good name.Part of good style is good naming. You want your method name to succinctly describe what it does. Never call a method doStuff, give it a good specific name like isOdd. Be consistent in how you name your methods. In our solutions, we will use lower camel case naming conventions.CommentingMake sure to comment every method you write, and describe what the method does, and what the assumptions are before and after it is called. Write your comments so that your program could easily be understood by another person. In general, remember to have one comment describing the entire program, thena few lines above the function header for each function describing the purpose of the function,plus any pre-conditions or assumptions of the function and maybe some lines elaborating uponthe parameters if necessary. It's also good to comment when you're writing code that deals withan edge case or when your code refers to other sections of your code so the reader doesn't have to scroll everywhere. Commenting is best done while coding, not after youve finished.But there's such a thing as too much of a good thing. To illustrate, here's an example of over- commented code:for (int /*i is of type int*/ i = 0 /*initializing the variable i*/; i < 10;i+ /*incrementing i by one*/) /the start of the body of the forloopprintln/*prints the following string*/(/*here comes the string!*/"Hello, World!"/*that was the string!*/); /the end of the body of forloopDecompositionThe general idea is the following: if a block of code performs a specific solitary function. These numbers are not meant to be taken verbatim; always use your judgement.Someone whos never seen any code before should be able to figure out your program's algorithm merely from looking at your run() function. Good function naming also plays a role, here, too, obviously, but the main point is about decomposition.Good:bool IsCoordValid(int row, int col, int maxRows, int maxCols) return (row >= 0) && (row < maxRows) && (col >= 0) && (col < maxCols);Bad:int Zero() return 0;WhitespaceInside a function, statements which form logical actions should be grouped together with adequate space to set it apart from the rest of the code. Variable declarations should also be set apart.There's another kind of whitespace that's important, horizontal whitespace:/* many terms with no spaces: never do this */int i=2*i+12/i;/* spaces around every operator: good */int i = 2 * i + 12 / i;/* using parentheses for readability and grouping: the best */int i = (2 * i) + (12 / i);Instance vs. Local VariablesIt can be tempting to make everything an instance variable, once you've used them a few times. You should use as few instance variables as possible. Constants, on the other hand, are usually declared outside of functions (and hence have the same scope as instance variables).Always Use Constants:Our code should never contain “magic numbers,” meaning numbers we use in our code that dont have a clear meaning. For example don't just have “7,” say DAYS_IN_WEEK. Instead of “10,” we write EYE_RADIUS. Well-named constants make it clear what the purpose of the variable is, and also reduce errors. If someone wants to change the EYE_RADIUS, they can modify its value everywhere in the program by only changing it once. If we just wrote “10,” they would have to go searching through the code to find all the places we use this value. The only numbers we don't need to turn into constants are the numbers 0,1 and sometimes 2.General and Reusable Methods:It is important to write methods that are general and reusable. If you find yourself copying and pasting code, this is probably a sign that you should have a more general method to accomplish this task. However, figuring out how to write general and reusable methods is an art, and is quite challenging. Look for similarities in your code, or ask yourself how you can use parameters.There Are Many Ways To Solve the Same Problem:Every problem can be solved in a number of ways. When you write your own programs try and consider the many ways to solve the problem, and the trade-offs and benefits of each solution.Short MethodsWe could have written our whole program in the run method, but it is not good style and is difficult to follow. Try and break it down into methods that are small, understandable pieces of code, and accomplish one main task.Contributors:bgwinesjkeeshinFurther Reference:http:/www.cs.arizona.edu/mccann/style_c.htmlAre you an SL who would like to contribute or improve this document? Email jkeeshinstanford.edu