The program has to work, a program has to be readable to humans. When we grade your projects, we shall look for specific things. By following these guidelines, you will write clearer code, your program will be easier to debug, will likely work better, we can grade your work more easily, and you will get more points.

Comments

We require file header comments, function header comments, and paragraph comments. The file header includes a list of the contents of the file and a brief description of the purpose of the file. A source file is a package of related functions. State the purpose of the package. Function headers should include the purpose, the args, the return value. Paragraph headers can be a single line but should provide minor narration. Well-designed, short functions do not need them.

Short and Narrow Functions

No function should be more than 30 lines. If you can't see the function on a single screen, you can't understand or debug it easily. A function should do one thing well and call other functions to handle subordinate operations. Breaking a task into a set of layers of functions, each one simple and hiding the details of the layers below it is the hardest part of software design. But it's worth it.

A function should not have indenting that requires a wide screen. Some people have nested ifs, whiles, fors, that go so far to the right that they do not fit on a printed page and require expanding a temrminal window to cinerama size (look that up on the web.) A function should not be more than 80 columns wide. If the nesting is getting too deep, make sub functions. It's worth it.

Handle Errors

System calls all return -1 on error. Your code has to check for -1 for every system call you make. The extra error checking will increase the size of your code, but it will prevent surprising errors.

Error messages should be sent to stderr using perror or fprintf(stderr. Programs that encounter errors must return or exit with a non-zero status.

No Compiler Warnings

Henceforth, all programs must be compiled with gcc -Wall and must report no errors. gcc will report any odd features in your program. Some of them will be easily fixed by including the appropriate header file. Some will reflect subtle bugs. You must produce code that compiles cleanly and include the compilation in your typescript.