These notes provide guidelines for internal program documentation and style. Although they are intended for student programmers, style skills will carry over into professional life after school. In fact, most professional programmers would consider these standards to be less than minimum requirements for commercial-quality software documentation. While geared mainly for a block structured language such as Pascal or C, most of the points discussed are applicable to any programming language. We will not address the ``how'' of program specification, design, or testing; these topics are the domain of the Computer Science curriculum.
The essence of good programming style is communication. Good style in programming is roughly as difficult to learn as good style in English. In both cases, the document has no value if it does not convey its meaning to the reader. Any program that will be used must be maintained by somebody - and that somebody must be able to understand the code by reading it. Any program that needs debugging will be easier to debug if the creator carefully explains what's going on.
Within the program text, programmers have three primary tools for communicating their intentions: comments (explanation for the program); clear variable names, constants, expressions and subroutines (the words of the program itself); and white space and alignment (the organization of the words in the program). Each of these aspects aid communication between the program writer and the program reader (which includes the program writer at debug time - so you as a program writer have a stake in good style too!).
I would advise anybody who expects to spend a lot of time at a keyboard to become a proficient typist, and learn the touch-typing method. If you never had a typing class in high school, there are many books available that will let you teach yourself.
Students who are poor typists may feel that adding comments to their program will increase the time spent when writing a program. Those students will quickly find that typing is the easiest part of programming. Finding and fixing syntax errors also becomes quite easy after a little practice, since the compiler gives you at least a clue as to how and where you went wrong. The time consuming part for many programmers is debugging. When you debug a program, you switch from being a program writer to being a program reader. This is where good style and commenting can save you many hours of hardship. The rules of programming style outlined here were developed by programmers who learned the hard way that using good style is a self-defense measure that minimizes bugs.