CS 142 Style Guide Grading and Details In the English language, there are many different ways to convey a message or idea: some ways are acceptable, whereas others are not. Similarly, there are acceptable and unacceptable methods for coding. In order to help you establish good coding practices we have created a style guide. Most companies have a coding style guide that all programmers follow in order to make it easier to understand and adapt code. We do the same for this class and expect everyone to follow the style guide. This makes it so that TAs know how to grade your style and you know what to expect. Get in the habit of using correct style when you first start writing code, rather than going back later to fix it up. You should be proud of how your code looks! Grading: It is possible that your text or instructor may use a style different than the ones described in the style guide, but your grading will be based on the style guide. Each main lab (or exam) can receive up to 100 auto-grade points based on your zybook submission. After you request grading, a TA grades your submission for adherence to 1) the style guide, and 2) any special requirements outlined in the lab specification. Special requirements are there to help you learn the key goals of the lab. They are graded all or nothing (unless stated otherwise), in that you lose all the requirement points if you do not comply. For each lab, there is a 3 point deduction for the first infraction of a style. There is a 1 point deduction for each subsequent infraction of that style up to a maximum of 6 points per style. The maximum points you can lose for style infractions is listed in each specification and is usually 20 points. To help you see our goal with this point system, consider the style indentation. If you did bad indentation 20 times in your program, we would not want you to lose all 20 points based on that one style error. We want to take off enough for the first incident (3 points) to get your attention so you will improve next time, and take off some points for repeated mistakes. In this case you would lose 3 points for the first infraction, and 1 point each for the next three with a maximum deduction of 6 for that style. The TAs will correct all style infractions in your code, so that you can learn and improve, even though you may have already exceeded the style deduction maximum. In the case of the descriptive names style, the infraction comes when you declare the variable. If you declare a variable with name "x" you will have 3 points deducted for bad naming, but not get another point off for each time that same variable "x" appears in your code. If you have another poorly named variable (e.g. "y") you will have another point deducted for its declaration, up to 6 points. Similarly, if you had the same magic number 371 appear multiple times in your program, rather than an appropriate constant, you would lose 3 points. If you had a different magic number (e.g. 13 occur multiple times), you would lose another point for that. You lose points for multiple infractions in the same line of code. If you declared a constant named zx, you would lose 3 points for bad naming, and also 3 points because constants must be all caps. Note that Self-Documenting Code has subcategories, so you could lose up to 6 points for each. Assume a lab has 3 special requirements each with a deduction of 10 points. Assume you received all 100 points for auto-grade, missed 12 style points, and you did not follow one of the special requirements. Your score would be 78. The TA then adds early points. If the lab is late by less than your remaining late days, the TA subtracts the number of late days from your total late day reserve. If the late days exceed your total, the lab will not be graded and you will receive a 0. TAs give clear feedback on points deducted, specifying where errors occurred, and give any other commentary needed to help you learn and do better the next time. You can view feedback from the TA in the feedback box for the assignment in learning suite. The feedback identifies which TA graded in case you have questions.
Variable Naming: How you name your variables is crucial to code readability. A good question to ask when naming a variable is, "If someone else saw this variable name, would they immediately know what it is used for?" Variable names must describe what they are used for, not describe the value they hold, since that value can change. Test Cases: The goal of test cases is to do our best to ensure code is working properly. We test for simple situations and also for less common cases. When testing a video game, testers do not simply play the game through; instead, they do obscure things such as walk into walls and corners, jump up trees, and cross invisible boundaries. Their goal is to do what we call break the code. They want to find all possible errors in the game, expose them, and then fix them. When you test your code, you want to consider where your code could fail, and then test your program such that you are testing the possible problem areas. You will include 3 example test cases for main labs (except where specifically noted). Three test cases are not enough to check all combinations. However, we consider the test cases you include as examples and evidence of your more thorough testing which you did above and beyond your three examples. Therefore, we expect your test cases to be diverse, attempting to test and explore different issues. If you do not include test cases you receive 3 points off for the first and 1 each for the others for a 5 point deduction. Your test cases must be your own. If you use a test case from the specification, or any of the visible test cases of the zybook auto-grader, you will be graded as if you had not written that test case. A key is that you should write test cases, including the output worked out by hand, BEFORE coding. One of the most helpful things about writing and solving a test case before coding is that it gives you the chance to think about the steps you have to take (as a human) to produce the correct output. If you do not understand the steps you must follow in order to generate correct output, it will be impossible to write a program to do so. If you create test cases after your program is done and just plug in the answers your code gives, you not only lose the comprehension benefits of test cases, but you do not even test if your code gives correct answers! On exams, we usually have you write at least one test case for your problem. Some students complain because even though they didn't completely finish the exam question, they still lost style points for not having a test case, which they planned on coming back and putting in after they got the program done. That is backwards! If they had done their test case first, they would have better understood the question, and perhaps got it working, and also received the style points. Following is an example of test cases. In the Pizza lab you will test with inputs that test different combinations such as just one of each type of pizza, all types of pizza, different sizes of tips, etc. For example on the Pizza lab you might first try with 1, 3, and 7 guests to test the one pizza each variations. Then, maybe test for one large pizza and one medium. Did that check out? If so, then test for one large, one medium, and one small. If that checks out, you move on to larger cases. The three test cases chosen from your more comprehensive testing reflect this effort. The Pizza lab does not ask you to test for incorrect input. Most labs will ask for that, and part of your testing must test to make sure your program handles "bad" inputs. In the first couple of labs you could actually just show the exact expected output that your program should give. However, this would get annoying as the full textual output for later programs could be very long and you really just want to focus on whether your program is getting the key calculated values right. In these cases, you do not need to write down all the formatted output text and you can focus on the information calculated and manipulated by the program. You can format your test cases however you would like as long as they are clear and easy to read, and clearly specify the inputs and expected output values. In the pizza lab one might show the following three test cases. (Do not use these exact cases as your examples).
/* Test 1: Input: (11, 10) Expected output: (1, 1, 1, 628.318, 57.1198,37) Result: Passed Test 2: Input: (4, 0) Expected output: (0, 1, 1, 314.159, 78.5392, 19) Result: 1, 1, 1, 444,234, 10.1 100 This led me to fix a bug where I had a wrong sign in my area equation Test 3: Input: (452, 15) Expected output: (64, 1, 1, 20420.3, 45.1777, 1102) Result: Passed */ Another resource to help you understand good test cases is to look at the test cases your code is tested with in the zybooks auto-grader. We use test cases to see if your code works and you could pattern some of your test cases after these. But come up with your own. Notice that our test cases try a variety of bad input and input which is intended to test what might be unusual cases (for example, places where you might have used ">" where you should have used ">="). In most cases it is impossible to test all possible inputs, so that is not what we are looking for, but rather that you are making an honest attempt to validate your code. One more test case example: Read this part once you get to the Plinko lab. Many wonder how to do tests with the Plinko lab where there are many more possibilities and there is also a random aspect to dropping a chip. Here is an approach I might use if I were in your place. I would want one test case that tested the possible types of input errors to ensure there is an appropriate re-request when an input error is made. Test Case #1 Input: The following test case is a stream of inputs which tests the possible erroneous input situations: -1, 4, 1, -3, 9, 4, 2,. (you fill in the rest) Expected output: Verify that an appropriate error message is given for each input error and that there is an appropriate re-request until a correct input is given. This communicates the full goal of this test case without having to show the long textual output which will actually be output. For the next two test cases I would want to make sure that I was getting correct outputs for drop one and drop multiple chips (in these cases not worrying about erroneous input which was tested in the first test case). With rand() we can set a fixed seed during testing so we know beforehand exactly what the random sequence will be. One approach is to write a separate tiny program, seed rand with a fixed value, and run a loop giving the first n (left, right) choices. Then I know exactly which direction will be chosen at each step. Then I could test what should happen when I drop a chip in any slot. Note that I try a drop in the middle but also one at each edge to make sure I am handling border cases. Test Case #2: Input: (using fixed seed of x) 1, 4, 1, 8, 1, 0, 0 Expected output: [4.0 4.5 5.0 5.5 5.0 5.5 5.0 4.5 4.0 3.5 4.0 4.5 5.0] Winnings: $0.00 [8.0 7.5 7.0 6.5 7.0 6.5 6.0 5.5 6.0 6.5 7.0 6.5 7.0] Winnings: $500.00 [1.0 1.5 1.0 1.5 2.0 2.5 3.0 3.5 3.0 3.5 4.0 4.5 4.0] Winnings: $10000.00 Test Case #3:
Input: (using fixed seed of x) 2, 2, 4, 0 Expected output: Total winnings: $1000.00 Average winnings per chip: $500.00 Magic Numbers: Literal numbers other than 0, 1, and -1 should rarely occur in the body of your code. Use constants or variables to replace magic numbers. Using constants has two important advantages. First, they make the code easier to read. Your code should read more like English prose with numbers replaced by descriptively named constants. Second, in cases where the programmer wants to later change the value of a constant, it need only be changed in one place at the declaration, and it will be updated in all places throughout the program. For example, you must never have a line of code in you program like: labgrade = labgrade + 4; In this case 4 is a magic number, where someone reading the code might not know what the 4 represents. Rather, you would declare and initialize a const variable at the top of your function and then later use it in your code. const int EARLY_HAND_IN_BONUS = 4; labgrade = labgrade + EARLY_HAND_IN_BONUS; To make grading, the only situations we will grade are for numeric values given in the assignment specification. For example, if a specification said that one large pizza serves 7, and the price of a large pizza is $13.98, then you must have two constants like the following used in your program. const int PEOPLE_SERVED_PER_LARGE_PIZZA = 7; const double PRICE_OF_LARGE_PIZZA = 13.98; We now give good practice for when "magic numbers" must be replaced by constants, but only the above cases will be graded. Just because a literal is 0 or 1 does not mean it should never be a constant. In fact, in cases except for those below, a 0 and 1 should usually be a constant. For example, in main lab #2 (Pizza) the spec states that a large pizza feeds 7, a medium 3, and a small 1. 7 and 3 are obvious magic numbers. But so is 1 in this case, both because the meaning of 1 in the coding context may not be obvious, and we may want to later change the number of people that a small pizza feeds. Times when 0, 1, and -1 are not magic numbers are: 1. Initializing variables 2. Resetting a counter 3. Incrementing or decrementing (though it is preferred you use ++ and --) 4. Simple boundary and index adjustment: for (int i = 0; i < str.size() 1; i++) 5. return 0 at the end of main The major exception for arbitrary numbers to not be constants are in common mathematical equations or arithmetic manipulations such as circumference = 2 * PI * radius; In this case you would be hard pressed to even think of a good name to replace the 2, and if you did it would probably make the formula less readable. Also, since it is a mathematical axiom, we would not be changing the value in the future, thus we would gain neither of the advantages of using constants.
Be careful NOT to use constants inappropriately as you will lose points if you do. Two common mistakes beginning students make are: 1. const int ZERO = 0; This does nothing of use. It does not make the code more readable (0 and ZERO are equivalent) and it does not make things more adaptable. You would never want to later set ZERO = 1. 2. const int FIVE_YEAR_LOAN_LIFE = 5; In this case the variable cannot be changed to another value (e.g. 10) without needing to change the name of the variable. Instead, name it something like LIFE_OF_LOAN, which is both descriptive AND can be changed later without needing to change the name. Thus never use the value of the constant as part of the name of a constant. One could argue that these cases better fall under variable naming, but since they happen most frequently with constants replacing magic numbers, we include it for both discussion and grading under magic numbers. Suggested Style Practices The style guide for companies is usually long and detailed. We previously used a longer style guide in 142, but decided to use a short version to let you learn and experience style without it becoming overbearing. Following are some of the styles which we used to grade. We suggest you follow these, but will not grade them. They improve code readability and decrease bugs. Initialize variables when they are declared. By initializing numbers to a consistent initial value (e.g. 0), you avoid difficult bugs when your code is mistakenly using an uninitialized variable that contains an unpredictable random value, giving unpredictable bugs. Some types, like strings, are automatically initialized. Integers, reals (double, float), Booleans, and characters should be initialized at the time of their declaration. Default values are 0, 0.0, false, and null (\0) respectively, if not initialized to a program specific value. int main() { const double ROCKET_SPEED = 3456.78; int planetsvisited = 0; bool arewethereyet = false; // You could use 0 or false here double distancefromsun = 0.0; char currentquadrant = '\0'; Whitespace: While the compiler ignores whitespace, how you use it greatly affects readability. To improve readability, the following spacing rules are suggested. 1. Each statement should appear on its own line. 2. Most items are separated by exactly one space, though there are common exceptions which you will see as you study more code. Common guidelines are: a. All binary operators (+. -. =, >>, etc.) have one preceding and following space b. No space precedes an ending semicolon c. No space follows a "(" or precedes a ")" 3. Lines of code are less than 120 characters; if necessary continue on a newline with an indent. 4. Leave a blank line between distinct sections of code. Functions: Functions should do one task. For example, you would not want a function that both a) returns the total number of words in a document and b) capitalizes first letters of all the words. Those should be done by separate functions, making them simpler and more general to use and adapt in the future. Functions should be kept short as possible, making them more readable and easier to write. Functions are structured to avoid duplication of code. You should not have places in your code where you have snippets of the same code many times, which is better handled by a function call each time. With void functions, return can be used for returning early in the function, but unlike non-void functions, it is optional whether you put a "return" at the end.
Miscellaneous: Following are other suggested guidelines: Do not use global variables, except for constants which are used in multiple functions int main() must end with return 0; Never use the C++ command "goto" Use endl rather than "\n" where possible For Classes: o Always create your own default constructor for each class, and create a parameterized constructor(s) when needed (usually). You may combine these into one constructor function by creating a default constructor with default parameters. o Any member function that will not mutate data members should be declared as const. o All data members and helper functions should be private (or protected). Conclusion: We will not take off points for style decisions a student makes for situations not specified in the style guide. We cannot mention all possible bad style decisions one might make (see Mosiah 4:29,30). If a TA sees that you did something inappropriate, they will help you by pointing it out, but not taking off points.