Style

1. Style Notes on commenting and programming style

2. Header Comments • Each program should start with a header comment • The header comment should: • Indicate the purpose for the program, • The date of completion, • The name of the programmer, • Any special notes about the use of the program or known bugs

3. Example //////////////////////////////////////////////////// // Example Program: // This is the example for the header comment. This // is where the purpose for the program would go. // You want to write as much as you need to explain // what this program does; a paragraph or two might // be enough. // // Date: October 18, 2004 // Programmer: David McPherson // // Additional Notes: Here’s where you can put // any extra stuff that you need to say. //

4. Function Headers • As we get into writing functions, each function needs a header. • The function header is similar to the program header. • The function header should • Give the name, • Give the purpose • List the parameters and the passing mechanism for the parameters • It can also list pre and post conditions.

5. Example //////////////////////////////////////////////////// // Function: SampleFunction // // This is a sample of what a function header // might look like. A paragraph of text here explains // what this function does. // // Parameters: // int x – this is the parameter for x. It is used // giving x to the function. // double y – this is the parameter y. It is used // to pass y back to the calling function. //

6. Other Comments • Headers are not the only location for comments. • Each block should start with a brief comment explaining what is going on. • Each variable should have a comment explaining its purpose in addition to a good choice for its name • Any time that the code is doing something that is not evident, you should comment.

7. Other matters of style • CONSTANTS SHOULD BE IN ALL CAPS • Variables should be named so that its purpose might be gleaned. • Make go use of whitespace • Don’t jam all your code together