Coding is an individualistic act, similar to writing. So the guidelines below should be taken as advice, not rules. The guidelines are intended to help you write easily readable code. Writing readable code is an important skill, and has several benefits.
- It makes it easier for you and your lab partners to understand your code.
- It makes it easier for you to debug your code.
- It makes it easier for your professor to help you debug your code.
- It makes it easier for you to go back and modify your code later on. (You will forget why you did what you did after some period of time.)
- It makes it possible for other people to understand and modify your code.
- It makes it easier to grade, and the professor is much happier during the process of grading. Happiness has a significant positive effect on grades.
So here are some guidelines for writing code. The details of writing comments are language dependent, but the overall guidelines are similar across languages.
- Put a brief description of each function in a block comment above its function declaration. Descriptions of each parameter (if any) and the return value (if any) are the most useful pieces of information to have for anyone who wants to use the function.
-
Variable names should be descriptive, with the exception of loop
variables. Using caps to separate subwords within a name or
underscores is a personal decision. I like doing variable names with
caps on subwords, like curImageData.
The exception to the descriptive names guideline are loop variables. The variable names i, j, k make great loop variables. Likewise, p and q make good temporary pointers for things like manipulating lists or binary trees. The i, j, k tradition goes back to the Fortran days of programming, where those variables were automatically declared as integers.
One place where you have to be careful about i, j is when you are working with images. Always remember that i is generally your row variable (outer loop) and j is generally your column variable (inner loop) and so they correspond to the y-axis and x-axis, respectively, in typical usage. Put in comments whenever you use i or j as mathematical x or y values.
- Put comments on the same line as or just above any really important variable declarations.
- Space. Put a blank line after the variable declarations, above and below any code block, and above and below any coherent block of code, such as a sequence of operations to implement a complex equation. A code block includes a for loop, while loop, or if-then-else construct.
- Comments. Put a one-line comment above any code block and above any coherent block of code, such as a sequence of operations to implement a complex equation. The blank line, mentioned above, should go above the comment, so that the comment is attached to the code. Ideally, someone reading your code should be able to read the one-line comments to understand the algorithm and not have to look at the code itself to understand the sequence of operations.
- Neatness. Generally try to make your code look neat. Don't be excessive about it, but avoid sloppy-looking or thick code, and be consistent how you use different kinds of syntax. If you don't naturally write that way, use a code beautifier every once in a while. Programs such as indent can do a nice job or organizing your code in a standardized way.
- For command line programs, use print statements liberally to alert you to the significant steps your program is taking. If you naturally include them before significant code blocks, then when things go wrong you know where they went wrong, and possibly why. It's also nice to be able to watch your code running and make sure it's following the sequence of actions you think it should.