Programming With Style
Contents of Chapter 1
There is a significant difference between having mastered the syntax of a language and being capable of writing readable programs. Becoming an expert programmer is a long journey. It takes years of experience to discover what makes good code readable and maintainable, and poor code tangled and hard to modify. The intention of this handbook is to provide a shortcut for the average programmer to learn how to produce readable and maintainable code; that is, how to program with style.
As a general purpose language, English serves us well for day to day activities, although historically it has often been insufficient for communicating complex concepts and specialized situations. For example, over the centuries notations have evolved out of the necessity to represent music and mathematics in a manner that is not feasible with the spoken word. A programming language is also a form of notation used to express operations mostly outside of our prosaic experiences.
Being a specialized notation, program source code is often difficult for the outsider or beginner to comprehend. Once mastered, however, code becomes easier to read than its English equivalent. The overall readability of a program should not be measured by how close a program is to English text, but by how effectively it expresses its functionality to the average reader.[Ranade and Nash 93]
Every program should have two distinct goals. First, to reliably execute the task it was designed to perform. Second, to communicate to people other than the original developer exactly what the code is doing. It is unfortunate that the second goal is often overlooked, because it is what distinguishes ordinary from extraordinary code! This handbook will focus on the second goal, of effectively communicating what code is doing, by following the "five C's" of good communication as they relate to C/C++, Smalltalk, Assembler, Scheme, and Lisp. The five principles are:
Briefly, source code must clearly convey its functionality to the reader through both code structure and effective documentation. In the real world, most applications are written in a team environment. For this reason, learning how to follow a standard coding style will make you a more valuable member of any software development group. As well, confusing code can be downright dangerous; that is, it may hide a potential bug in the code.
Next, the code should comprehensively provide all the information that the reader may need by stressing indirect and direct documentation. Although the idea of concise code may seem to contest code clarity and comprehensiveness, it is important to realize that source code must not be too verbose. Use the tools provided by the language, but do not try to squeeze as many tricks as possible into each line of code. A delicate balance must be achieved with regard to this principle to maximize readability.
Whether you decide to follow the recommendations in this book, or develop your own rules, you must use them consistently. Every effort has been made to ensure that the style guidelines presented here are general enough to handle most situations. Please realize that although consistency is important, blind obedience is not. If following one of the suggestions in this handbook will result in poor code, simply do not use it for that situation.
Finally, just as it is important for code to be correct (error free), it is equally critical that comments be accurate; a road sign pointing in the wrong direction is worse than no road sign at all. Standardizing programming style is an effective means of decreasing the opportunity for errors. As well, sloppy code can make the reader doubt the professionalism of the programmer, and therefore, the reliability of the code.[Straker 92]
By making a concerted effort to exercise the five keys of communication, we will have inadvertently applied a sixth principle, consideration. In other words, we will have shown thoughtfulness for the person who may need to read your code in the future, and even for yourself if you have to go back and review your program months from now. The idea of consideration is one of the underlying themes of this handbook, and it will be reiterated throughout.
1.1 Standards versus guidelines
Unlike software engineering, other engineering disciplines have well established standards which are recognized as being essential to the practical and economic production of quality products. Where do guidelines fit in? First, it is important to draw the distinction between standards and guidelines.
By definition, a standard is a fixed mark or measure of excellence that defines how something can be made with consistency. Standards are established to be both followed and enforced. In contrast, a guideline is a directing principle which indicates the recommended path one should take given a set of circumstances. Guidelines are suggested but not enforced; the user must decide whether or not the guideline is useful depending on the situation. This manual will recommend both standards and guidelines.
1.2 Programming standards versus coding standards
The terms "programming standard" and "coding standard" are often used interchangeably. In reality, they represent two quite different concepts. More specifically, programming standards imply the whole spectrum of activities involved in writing programs from start to finish. These activities entail specifying, designing, implementing, testing, debugging, and optimizing complete programs. Clearly, programming standards can be quite broad in scope.
Coding standards imply the specific act of writing code, possibly from a very detailed design. Coding skills are based on the ability to understand a design and translate it into code. The coding standards presented in Part 2 of this book are mainly concerned with the issues of readable code layout and language usage.
It would be silly to pretend that there is only one way to write readable code. Some issues of programming style are not black and white, and require the programmer to make a judgement call based on experience. As explained in section 1.1, the distinction between standards and guidelines must be acknowledged. This handbook provides specific standards for clear-cut issues, as well as guidelines for areas which have several alternative methods. In all cases, I have outlined the reasoning behind the standard or guideline, as well as easy to reference summaries at the end of each chapter.
The organization of the handbook also recognizes the contrast between programming standards and coding standards. The remaining two chapters (2.0 and 3.0) of Part 1, will deal with programming standards. The chapters in Part 2, will offer practical coding standards and guidelines for the C/C++, Smalltalk, Assembler, Scheme, and Lisp programming languages.
1.4 Who will these standards benefit?
First and foremost, these standards will benefit other people. That is, they will help other programmers who may need to understand your code (perhaps to interface their code to it), to check your code for bugs, to port your code to different software or hardware platforms, or to enhance your code in the future. As mentioned, the underlying moral of this work is to convince you of the importance of showing consideration for these people.
Secondly, the coding standards will benefit you, the original programmer. They will help you to make consistent and logical decisions regarding code layout and language usage, to decrease the opportunity for errors, to give you the recognition of having written clear and understandable code, and to help you to work with a program that another programmer may have written following the same coding style. Even if you do not work in a team environment, following standards can give you a sense of professionalism and satisfaction in a job well done. Sir Ernest Gowers once wrote, "to be clear is professional; not to be clear is unprofessional."[Peter's Book of Quotations]
1.5 What are these standards for?
Programming and coding standards are beneficial to software construction in three main ways.[Straker 92] They:
Overall code quality is enhanced because good standards promote code which is easy to test, with few potential bugs, and good error handling capabilities. By following coding standards, code understandability is enriched which improves future program maintainability. In other words, enhancements and bug fixes are easier to make with readable code. Improved maintainability helps to increase programmer productivity by making future program support less arduous. Programming standards also aid productivity by encouraging the use of available tools to reduce development effort, advising on issues of portability, and encouraging code reuse. All of these benefits can be realized through the implementation of standards.
Inexperienced programmers often have misconceptions regarding standardization:
Fallacy: Coding standards are just the current fashion.
Response: For the most part, fashions become popular for emotional, not logical, reasons. You will discover that every point of style presented within these pages has a logical reason or purpose. Also, because software systems are becoming increasingly complex, standards are essential and definitely here to stay.
Fallacy: The interference of standards will impair programmer creativity.
Response: Any advanced programmer will tell you that the creative element of programming is more in the design stage, than in the coding phase. The translation of a design into an implementation language should be a straightforward process.
Fallacy: Standards decrease productivity by forcing unnecessary actions.
Response: To the narrow minded programmer who believes that "real programmers write code, not documentation" this point may seem valid. In truth, the actual time spent typing code is only a small proportion of the total programming effort which involves, among other things, design, testing, debugging, optimizing, and modifying. As section 1.5 made clear, standards actually improve programmer productivity by making code easier to test and maintain.
Fallacy: Standards do not prevent bugs.
Response: Implementing standards makes common coding tasks more mechanical, giving the expert programmer more time to think about getting the rest of the program right. Without a doubt, writing comments and devising meaningful identifier names means considering how the program can be explained to others -- this is often a great way to spot potential problems.
Obviously, most arguments against coding standards are based on irrational perspectives. Overcoming misconceptions, such as those above, is often the greatest hurdle to the implementation of computing standards.
The degree of programming standardization required depends on the situation. Consider a large development team, with high staff turn over, producing a complicated end product, with high maintenance requirements. In this case, the enforcement of a very rigorous and detailed standard may be called for. On the other hand, if the programming team is relatively small, with stable professional staffing, then perhaps a few general guidelines will suffice. Keep in mind that large systems often grow from small ones.
Implementing a coding standard requires four steps to be performed. First, awareness for the need of standardization must be raised. Second, common misconceptions must be dealt with. Next, the standard must be defined by collecting opinions and ideas and formalizing them into a description of the standard, complete with reasons why certain practices should be avoided with supporting evidence. Finally, standards must be brought into use by the programming team or organization and enforced!
To truly program with style, follow the basic principles that have been outlined in this chapter: