This file is intended as a guide to help you understand good coding principles, with the added incentive of getting higher grades on homework (and making your friendly-neighborhood TA much happier and headache-free). We grade homework based upon both "external correctness" (it "works") and "internal correctness" (good style). Efficiency is sometimes part of external correctness and sometimes part of internal correctness. Regardless, homework points are usually distributed approximately equally between the two. 1. Properly head your assignment. Include the following. a. Your first and last name. b. The date that you turned the assignment in. c. Your class ("CSE143 AD") d. Your TA ("") e. The assignment name and number. 2. Format your code so the printouts are neat. Illegible printouts do not encourage high grades. a. Put longer comments on the preceeding line. For example: DON'T: x = function(y); // blah blah blah blah blah blah blah blah... DO: // blah blah blah blah blah blah blah blah x = function(y); This makes the printouts readable, and helps me find ways to give back points. Illegible printouts do not encourage high grades. b. Break up long lines into multiple lines. A single line should not span more than 80 characters. 3. Comment well. Explain the principle workings and any special or unexpected results of the function. While do cover all the details, there is no need to write an essay, and please do not copy what Stuart Reges writes in the problem handouts. The most important part is to be consistent. The pre/post paradigm is a great and concise way to comment; however, you are not required to use it. 4. Style points a. Name your variables and functions well. Don't call it 'x' when you mean 'prime' (or some other descriptive term). Avoid all generic names such as 'x', 'function', and 'stuff' when a better name exists. Realize, however, that in some situations, such as a for loop, a monocharacter variable such as 'i' is the best option. b. Code with boolean zen. DON'T: if (bool == true) DO: if (bool) DON'T: return bool == false; DO: return !bool; // returns the logical opposite of bool // '!' makes true become false and false DON'T: if (bool) // become true return true; else return false; DO: return bool; c. Use consistent coding technique. Indent every code block and equal number of sentences. Always indent the code within braces ('{' and '}'). Also indent after for, while, and if statements with no braces. DON'T: if (something) function(); DO: if (something) function(); I personally recommend indenting by two spaces. The following is an example of code that I would prefer. However, you are free to use any coding style that is consistent. public class Something extends SomethingElse { public String text; // Comment the function here. // Include all major details. // Pre/Post commenting is usually a safe bet. void function(int number) { // Put long comments on the line before for (int i=0; i<5; i++) { if (bool) dosomething(); System.out.println("Hello world!"); } } } d. Make new methods only where it makes sense. This might be when you do the same thing multiple times or when you're able to decompose your code into methods that divide the task naturally. e. Don't repeat code if it can be avoided. One way of not repeating code is by making methods. Another place is when writing programs that have multiple constructors, you should only initialize fields in one of the constructors, and have the rest of the constructors call this one constructor using "this". DON'T: public class Something{ private int i; private File f; //constructor 1... public Something(){ i = 0; f = new File("default.txt"); } //constructor 2... public Something(int anInt){ i = anInt; f = new File("default.txt"); } //constructor 3... public Something(int anInt, File aFile){ i = anInt; f = aFile; } } DO: public class Something{ private int i; private File f; //constructor 1... public Something(){ this(0, "default.txt"); } //constructor 2... public Something(int anInt){ this(anInt,"default.txt"); } //constructor 3... public Something(int anInt, String aFileName){ i = anInt; f = new File(aFileName); } } f. Initialize all class-level fields in the constructor, not at the top of the class where you declare the fields. DON'T: public class Something{ private int i = 1; private File f = new File("blah.txt"); //constructor... public Something(){} } DO: public class Something{ private int i; private File f; //constructor... public Something(){ i = 1; f = new File("blah.txt"); } } g. Declare variables in the most local scope as possible. In other words, if you only need a variable in a single method, declare that variable in that method, not at the class-level (right after you declare your class). Having variables around when you're not using them and never will makes programs unnecessarily take up more memory. 5. Make sure your output matches the homework description exactly, especially whitespace. A single character difference can lose you points.