CSE 11 Style Guidelines

Transcription

1 CSE 11 Style Guidelines These style guidelines are based off of Google s Java Style Guide and Oracle s Javadoc Guide. Overview: Your style will be graded on the following items: File Headers Class Headers Method and Constructor Headers Comments Magic Numbers Variable Names Use of Whitespace 80 Characters Per Line Other Failure to follow anything listed in this document will result in deductions from your programming assignments! File Headers: Every file needs a file header (yes, even the README). File headers are always required at the very top of every file regardless of whether it is code you wrote or code that came from the textbook. This header needs to have the format of: /* * Filename: filename.java * Author: Your name * UserId: Your cs11fxxx account * Date: Date when file was created * Sources of help: All sources of help you used (tutors, Piazza posts, books, * websites, etc.). Other students should not be listed here as * other students should not be looking at your code. * If you did not use any sources of help, you MUST put "None".

2 Class Headers: Every class that is written by you needs a Javadoc class header. If a class is not written or modified by you (i.e., it came from the textbook and/or starter code), you do not need to write a class header for it, although it is always helpful to document your code. Class headers should be placed on the line immediately above the public class statement. This header needs to have the format of: /** * Description of the class and/or what it is used for. Keep this 1-2 lines. Method and Constructor Headers: Every method and constructor that is written by you needs a Javadoc method header. If a method/constructor is not written or modified by you (i.e., it came from the textbook and/or starter code), you do not need to write a header for it, although it is always helpful to document your code. Method/constructor headers should be placed on the line immediately above the method/constructor declaration. This header needs to have the format of: /** * Description of the method or constructor. Focus on what the method/constructor * does conceptually, and not necessarily how you implemented it. * nameofparam1 State what this parameter represents. nameofparam2 State what this parameter represents. nameofparam3 State what this parameter represents. Specify what the return value represents. Note: When using tag, nameofparamx should purely be the name of the formal parameter, and should not include the type When using tag, do not add any punctuation between the name of a parameter and its description specifying what the parameter represents. If a method does not have any parameters, do not put tag. If a method does not have a return value, do not put tag. For any further questions on method headers, refer to Oracle s Javadoc Guide. Comments: Well documented code is good code. Commenting is a skill that you will develop in time, but here are some guidelines to help jump start the process. Content of Comments: Write reasonable comments to make your code clear and readable. The purpose of comments is to make it immediately clear what your code is doing at first glance. If you can t glance at your code and immediately

3 have a good idea of what the code is doing, then you should add a comment summarizing the purpose of that block or line of code and what it is doing. You should mainly comment: Logical blocks of code that work together towards a single goal or purpose Single lines of code that are complicated or difficult to understand at first glance Single lines of code that look simple but serve a purpose that is not immediately obvious Avoid commenting: Every single line of code; If you find yourself needing to comment every line of code to be able to understand it at first glance, you should split up your code into simpler statements. Simple lines of code that are easily understood at first glance for example, avoid adding comments like: x++; // increment x Formatting Comments: Single-Line Comments: // This is a short comment /* This is a short comment Multiple-Line Comments: /* * This is a comment that is longer than the shorter * comment that is written above. /* This is a comment that is longer than the shorter * comment that is written above. // This is a comment that is longer than the shorter // comment that is written above. Requirements for Formatting Comments: Be consistent with how you format your comments, this will improve readability Place comments directly above the code they are commenting Short comments may be placed on the same line of code they are commenting, as long as it does not clutter your code and/or make it difficult to read Magic Numbers: No Magic Numbers! Any numbers other than 0, 1, and -1 are magic numbers. In the event you need to use a number (it happens a lot), define a static final constant at the top of the class. The name of the constant should be in all uppercase letters (using underscores between words), and should indicate the meaning of the number (what it is used for/what it represents). Using constants in this way (instead of magic numbers) will improve the readability and maintainability of your code. Examples: private static final int CHAR_WIDTH = 40; private static final int HALF_CHAR_WIDTH = CHAR_WIDTH / 2;

4 IMPORTANT: Give your constants meaningful names. Simply saying: private static final double TWO = 2.0; is not good enough; TWO gives no indication of what the constant is used for, and does nothing to improve the readability or maintainability of your code. If the purpose of this constant is to divide numbers in half, a better name would be something like: private static final double HALF_DIVISOR = 2.0; [See PA1 starter code for more examples] Variable Names: Use reasonable names for your variables and constants. The names of variables/constants should indicate their purpose/what they represent. This greatly improves readability and helps others (and yourself) more easily follow your code. Capitalization: Convention Example Variables Constants camelcase--each word after the first begins with an uppercase letter all uppercase with underscores between words numofturtles NUM_OF_TURTLES Use of Whitespace: Indentation: Use 2 spaces for each level of indentation. Make sure each level of indentation lines up evenly. Every time you open a new block of code (meaning you use an opening curly brace: { ), increase the level of indentation on the next line. Go back to the previous level of indentation when you close the block (meaning you use a closing curly brace: } ). No tabs! See the Google Java Style Guide for more info. In Java, when a long line is split among 2 lines, make sure to indent the second line farther than the first to indicate that it is a continuation of the previous line. There are many different ways to do this depending on the situation, however, the overall goal is to improve readability. The following are some examples. Long parameter lists: Break the line on any of the commas, then line up the second line with the first parameter provided. variable = object.reallylongmethodname(param0, param1, param2, param3, param4, param5);

5 Long parameter names: Break the line on the opening paren of the parameter list, then indent the subsequent lines in a way that enhances readability (two levels of indentation is a good rule of thumb). variable = object.reallyreallylongmethodname( thisisthefirstparambeingpassed, thisisthesecondparambeingpassed); Long expression using infix operators: Break the line on the infix operators and line up the second line with to be on the right hand side of the equals sign. variable = long + string * of - infix % operations; Newlines: Whitespace is your friend! Separate logical blocks of code with a blank line in between. It is a lot harder to debug a wall of text than it is to work with something that is broken up. However, don t go overboard. You don t need to have a newline between every two unrelated lines of code, and definitely don t use too many at once. Make sure to remove any excessive newlines at the end of each file. Binary Operators: Make sure to use spaces around binary operators--this greatly improves readability. For example: Good Bad for (int index = foo; index < (foo * (bar + baz)); index += STEP_AMT) {... } for (int index=foo; index<(foo*(bar+baz)); index+=step_amt) {... } [note that this applies to binary operators in general, not just binary operators in for-loops] [See PA1 starter code for more examples] 80 Characters Per Line: No lines over 80 characters! If you have a line that is 81+ characters, break it into two lines (following the rules on indentation above). Be very careful when writing comments as those tend to be where students get deducted. Also keep in mind that whitespace characters count towards the 80-character rule. Add the following lines to your.vimrc file to easily detect characters beyond the 80 character limit. (Lines beginning with quotation marks are just comments to explain what the following command does.) " Highlight the 80th column (can change to 81st column if you prefer) set colorcolumn=80 " Highlight text over 80 characters in red match Error /\%81v.\+/

6 Other: Commented-out Code: Remove any and all commented-out code before turning your assignments in. Leave only what is relevant. TODO s: Once a TODO is TODONE (meaning you completed the task that needed to be done), remove the TODO from your code. You must remove all TODO s from your code before turning your assignments in.