ICS 22 / CSE 22 Fall 2012
Style and Documentation Standards


Writing high-quality programs using good style is important, for many reasons. Professional programmers need not only to be able to read and understand their own code, months or even years after originally writing it, but also to be able to read and understand code written by others, oftentimes in the absence of the original author. Programmers who write code in a clear style with adequate documentation benefit not only themselves, but all other current and future members of their team. There is nothing more frustrating as a programmer than inheriting responsibility for someone else's code, only to find that the code is designed poorly, written cryptically, and documented shabbily (or not at all!). Having inherited plenty of code in my career that exhibited some or all of these shortcomings, I would be remiss if I did not insist that your code was better.

Of course, it's not enough for me to say that you should "use good style" or "write high-quality programs." These are terms that are obviously open to interpretation. I have adopted a set of specific standards that I would like you to follow when writing your Java code in my course. These standards are framed by one guiding principle: A program that can be read easily is one that can be understood easily, by the author as well as others. The standards are described in the list below.

A good example of many of these coding practices can be found by looking at the various starting points provided for each project or the code examples that I provide from lecture. Some of these files do not follow all of the rules above, particularly the rule regarding a comment on every method (since we expect you to write these comments yourself, in some cases), but they are still a useful way to see many of these rules in action.