There once was a man who went to a computer trade show. Each day as he entered, the man told the guard at the door: "I am a great thief, renowned for my feats of shoplifting. Be forewarned, for this trade show shall not escape unplundered!"
This speech disturbed the guard greatly, because there were millions of dollars of the latest technology inside. So the guard watched the man like a hawk as he wandered from booth to booth humming quietly to himself. As the man was leaving the guard took him aside and searched his clothes, but found nothing.
On the next day of the trade show, the man returned and chided the guard saying, "I escaped with vast booty yesterday, but today will be even better." So the guard watched him even more closely, but, again, to no avail.
On the final day of the trade show, the guard could not restrain his curiosity any longer. "Sir," he said, "I am so puzzled, I cannot live in peace. Please enlighten me. What is it that you are stealing?"
The man smiled. "I am stealing ideas," he said.
This handbook is a collection of ideas. It represents an effort to compile existing software construction techniques regarding program design and style issues, under a single, comprehensive, and easy to use reference. The overall purpose of the work is to help programmers improve the readability and maintainability of their C/C++, Smalltalk, Assembler, Scheme, and Lisp programs. Real world coding advice will be presented to the reader through concrete examples and the reasoning behind the rules.
The techniques contained within these pages are not intended to deal with performance and portability issues, unless directly related to style, as these topics are large enough to be the subjects of whole books themselves. The guidelines given do, however, affect how easy it will be for you to understand, review, and edit code months after it has been written. As well, they influence how easy it will be for others to read, comprehend, and revise your code years from now. Long-term code maintainability is perhaps the best metric of code quality.[Oman 93]
The term "religion" is frequently used to describe the differing viewpoints regarding programming style. I have done my best to keep my own "religions" out of the discussion, and to present the style rules as objectively as possible. It is very likely that you will not agree with every idea presented within these pages. Nevertheless, the overall goal of the work is less to win your support for every little detail, than to persuade you to keep in mind the diverse issues involved in selecting and implementing a good programming style.
I sincerely hope that this handbook will not end up on a shelf gathering dust, only to be brought out to settle the occasional coding dispute. It is the kind of guide I would want at my side when writing programs, and that is the kind of guide that I believe I have written.
You. Whether you are an experienced programmer or a first year computer science student, the programming advice given will help you to produce code of greater readability and enhanced maintainability. For the seasoned programmer, this reference will serve as a comprehensive, yet easy to use, guide whether you are self-taught or formally trained.
Programming textbooks are often, understandably, more concerned with what can be done with a given language today, rather than how easy programs will be for others to read and understand tomorrow. As a result, many computer science students graduate with rich theoretical know-how, but lacking more practical coding skills. For students, this handbook could be considered a hand-up for making the transition from an educational environment to a professional one.
The handbook is arranged into two parts:
PART 1: Outlines the principles of constructing maintainable programs. The emphasis here is on programming with consideration for others, user-friendly programs, modular code construction, tips for program design, testing, debugging, and optimization, as well as a survey of helpful development tools such as debuggers, editors, and profilers.
PART 2: Provides very specific style rules for C/C++, Smalltalk, Assembler, Scheme, and Lisp. In addition, this section reveals the key psychological factors which must be considered when selecting and practising a given coding style.
Finally, in the appendices, I have included detailed style templates for the languages presented in Part 2 -- for easy reference.
Even expert programmers will admit that learning to write readable code is a never ending process. There are always new ideas to be mastered. When you are interested in improving your coding skills further, I would suggest: discussing ideas and techniques with your peers, reading well written code, having someone else review and comment on your code, and reading more publications related to the topic of programming with style. As a starting point, the bibliography for this handbook contains a list of highly recommended references.
As well as thanking the authors of those books, for their excellent (often conflicting) viewpoints, I would like to acknowledge the expert guidance of Professor Sophie Quigley. I must also thank all of the faculty members of the School of Computer Science for their insightful commentary and appraisal of my work. Finally, many thanks to the programmers and computer science students who have made conducting this research an outstanding learning experience.