26 A sense of style mplementing the object-oriented method requires paying attention to many details of style,which a less ambitious approach might consider trifles. 26.1 COSMETICS MATTERS! Although the rules appearing hereafter are not as fundamental as the principles of object- oriented software construction covered in earlier chapters,it would be foolish to dismiss them as just"cosmetics".Good software is good in the large and in the small,in its high- level architecture and in its low-level details.True,quality in the details does not guarantee quality of the whole;but sloppiness in the details usually indicates that something more serious is wrong too.(If you cannot get the cosmetics right,why should your customers believe that you can master the truly difficult aspects?)A serious engineering process requires doing everything right:the grandiose and the mundane So you should not neglect the relevance of such seemingly humble details as text layout and choice of names.True,it may seem surprising to move on,without lowering our level of attention,from the mathematical notion of sufficient completeness in formal specifications (in the chapter on abstract data types)to whether a semicolon should be preceded by a space (in the present chapter).The explanation is simply that both issues deserve our care,in the same way that when you write quality O-O software both the design and the realization will require your attention. We can take a cue from the notion of style in its literary sense.Although the first determinant of good writing is the author's basic ability to tell a story and devise a coherent structure,no text is successful until everything works:every paragraph,every sentence and every word. Applying the rules in practice Some of the rules of this chapter can be checked or,better yet,enforced from the start by software tools.Tools will not do everything,however,and there is no substitute for care in writing every piece of the software
26 A sense of style Implementing the object-oriented method requires paying attention to many details of style, which a less ambitious approach might consider trifles. 26.1 COSMETICS MATTERS! Although the rules appearing hereafter are not as fundamental as the principles of objectoriented software construction covered in earlier chapters, it would be foolish to dismiss them as just “cosmetics”. Good software is good in the large and in the small, in its highlevel architecture and in its low-level details. True, quality in the details does not guarantee quality of the whole; but sloppiness in the details usually indicates that something more serious is wrong too. (If you cannot get the cosmetics right, why should your customers believe that you can master the truly difficult aspects?) A serious engineering process requires doing everything right: the grandiose and the mundane. So you should not neglect the relevance of such seemingly humble details as text layout and choice of names. True, it may seem surprising to move on, without lowering our level of attention, from the mathematical notion of sufficient completeness in formal specifications (in the chapter on abstract data types) to whether a semicolon should be preceded by a space (in the present chapter). The explanation is simply that both issues deserve our care, in the same way that when you write quality O-O software both the design and the realization will require your attention. We can take a cue from the notion of style in its literary sense. Although the first determinant of good writing is the author’s basic ability to tell a story and devise a coherent structure, no text is successful until everything works: every paragraph, every sentence and every word. Applying the rules in practice Some of the rules of this chapter can be checked or, better yet, enforced from the start by software tools. Tools will not do everything, however, and there is no substitute for care in writing every piece of the software
876 A SENSE OF STYLE $26.1 There is often a temptation to postpone the application of the rules,writing things casually at first and thinking"I will clean up everything later on;I do not even know how much of this will eventually be discarded".This is not the recommended way.Once you get used to the rules,they do not add any significant delay to the initial writing of the software;even without special tools,it is always more costly to fix the text later than to write it properly from the start.And given the pressure on software developers,there is ever a risk that you will forget or not find the time to clean things up.Then someone who is asked later to take up your work will waste more time than it would have cost you to write the proper header comments,devise the right feature names,apply the proper layout. That someone may be you. Terseness and explicitness Software styles have oscillated between the terse and the verbose.In programming languages,the two extremes are perhaps APL and Cobol.The contrast between the Fortran-C-C++line and the Algol-Pascal-Ada tradition -not just the languages themselves,but the styles they have bred-is almost as stark. What matters for us is clarity and,more generally,quality.Extreme forms of terseness and verbosity can both work against these goals.Cryptic C programs are unfortunately not limited to the famous"obfuscated C"and "Obfuscated C++"contests; but the almost equally famous DIVIDE DAYS BY 7 GIVING WEEKS of Cobol is a waste of everyone's attention. The style that follows from this chapter's rules is a particular mix of Algol-like explicitness(although not,it is hoped,verbosity)and telegram-style terseness.It never begrudges keystrokes,even lines,when they truly help make the software readable;for example,you will find rules that enjoin using clear identifiers based on full words,not abbreviations,as it is foolish to save a few letters by calling a feature disp (ambiguous) rather than display (clear and precise),or a class ACCNT (unpronounceable)rather than ACCOUNT.There is no tax on keystrokes.But at the same time when it comes to eliminating waste and unneeded redundancies the rules below are as pitiless as the recommendations of a General Accounting Office Special Commission on Improving Government.They limit header comments to indispensable words,getting rid of all the non-essential "the"and other such amenities;they proscribe over-qualification of feature names (as in account balance in a class ACCOUNT,where balance is perfectly sufficient);against dominant mores,they permit the grouping of related components of a complex construct on a single line,as in from i:=/invariant i<=n until i=n loop;and so on This combination of terseness and explicitness is what you should seek in your own texts.Do not waste space,as exaggerated size will in the end mean exaggerated complexity;but do not hesitate to use space when it is necessary to enhance clarity Also remember,iflike many people you are concerned about how much smaller the text of an object-oriented implementation will be than the text of a comparable C,Pascal, Ada or Fortran program,that the only interesting answer will appear at the level of a
876 A SENSE OF STYLE §26.1 There is often a temptation to postpone the application of the rules, writing things casually at first and thinking “I will clean up everything later on; I do not even know how much of this will eventually be discarded”. This is not the recommended way. Once you get used to the rules, they do not add any significant delay to the initial writing of the software; even without special tools, it is always more costly to fix the text later than to write it properly from the start. And given the pressure on software developers, there is ever a risk that you will forget or not find the time to clean things up. Then someone who is asked later to take up your work will waste more time than it would have cost you to write the proper header comments, devise the right feature names, apply the proper layout. That someone may be you. Terseness and explicitness Software styles have oscillated between the terse and the verbose. In programming languages, the two extremes are perhaps APL and Cobol. The contrast between the Fortran-C-C++ line and the Algol-Pascal-Ada tradition — not just the languages themselves, but the styles they have bred — is almost as stark. What matters for us is clarity and, more generally, quality. Extreme forms of terseness and verbosity can both work against these goals. Cryptic C programs are unfortunately not limited to the famous “obfuscated C” and “Obfuscated C++” contests; but the almost equally famous DIVIDE DAYS BY 7 GIVING WEEKS of Cobol is a waste of everyone’s attention. The style that follows from this chapter’s rules is a particular mix of Algol-like explicitness (although not, it is hoped, verbosity) and telegram-style terseness. It never begrudges keystrokes, even lines, when they truly help make the software readable; for example, you will find rules that enjoin using clear identifiers based on full words, not abbreviations, as it is foolish to save a few letters by calling a feature disp (ambiguous) rather than display (clear and precise), or a class ACCNT (unpronounceable) rather than ACCOUNT. There is no tax on keystrokes. But at the same time when it comes to eliminating waste and unneeded redundancies the rules below are as pitiless as the recommendations of a General Accounting Office Special Commission on Improving Government. They limit header comments to indispensable words, getting rid of all the non-essential “the” and other such amenities; they proscribe over-qualification of feature names (as in account_balance in a class ACCOUNT, where balance is perfectly sufficient); against dominant mores, they permit the grouping of related components of a complex construct on a single line, as in from i := 1 invariant i <= n until i = n loop; and so on. This combination of terseness and explicitness is what you should seek in your own texts. Do not waste space, as exaggerated size will in the end mean exaggerated complexity; but do not hesitate to use space when it is necessary to enhance clarity. Also remember, if like many people you are concerned about how much smaller the text of an object-oriented implementation will be than the text of a comparable C, Pascal, Ada or Fortran program, that the only interesting answer will appear at the level of a
$26.1 COSMETICS MATTERS! 877 significant system or subsystem.If you express a basic algorithm-at the level of Quicksort,say,or Euclid's algorithm-in C and in the notation of this book,expect the O-O version to be at least as large.In many cases,if you apply the principles thoroughly, it will be larger,since it will include assertions and more type information.Yet in ISE's experience of looking at medium-scale systems we have sometimes found(without being able to give a general law,as the circumstances vary considerably)the object-oriented solution to be several times smaller.Why?This is not due to terseness at the "micro"level but to systemwide application of the architectural techniques of the O-O method: Genericity is one of the key factors.We have found C programs that repeated essentially the same C code many times to handle different types.With a generic class-or for that matter a generic Ada package-you immediately get rid of that redundancy.It is disturbing in this respect to see that Java,a recent O-O language based on C,does not support genericity. Inheritance is also fundamental in gathering commonalities and removing duplications Dynamic binding replaces many complex decision structures by much shorter calls Assertions and the associated idea of Design by Contract avoid redundant error checking,a principal source of bloat. The exception mechanism gets rid of some error code. If you are concerned with source size,make sure to concentrate on these architectural aspects.You should also be terse in expressing algorithms,but never skimp on keystrokes at the expense of clarity The role of convention Most rules define a single permissible form,with no variants.The few exceptions include font use,which is governed by external considerations(what looks good in a book may not be visible on overhead transparencies),and semicolons,for which there exist two opposite schools with equally forceful arguments(although we will have a few universal rules anyway).In all other cases,in line with the introductory methodology chapter's exhortations against wishy-washiness,the rules leave about as much room to doubt as a past due reminder from the Internal Revenue Service. The rules are rooted in a careful analysis of what works and what works less well, resulting from many years of observation;some of the rationale will appear in the discussion.Even so,some rules may appear arbitrary at first,and indeed in a few cases the decision is a matter of taste,so that reasonable persons working from the same assumptions may disagree.If you object to one of the recommended conventions,you should define your own,provided you explain it in detail and document it explicitly;but do think carefully before making such a decision,so obvious are the advantages of abiding by a universal set of rules that have been systematically applied to thousands of classes over more than ten years,and that many people know and understand
§26.1 COSMETICS MATTERS! 877 significant system or subsystem. If you express a basic algorithm — at the level of Quicksort, say, or Euclid’s algorithm — in C and in the notation of this book, expect the O-O version to be at least as large. In many cases, if you apply the principles thoroughly, it will be larger, since it will include assertions and more type information. Yet in ISE’s experience of looking at medium-scale systems we have sometimes found (without being able to give a general law, as the circumstances vary considerably) the object-oriented solution to be several times smaller. Why? This is not due to terseness at the “micro” level but to systemwide application of the architectural techniques of the O-O method: • Genericity is one of the key factors. We have found C programs that repeated essentially the same C code many times to handle different types. With a generic class — or for that matter a generic Ada package — you immediately get rid of that redundancy. It is disturbing in this respect to see that Java, a recent O-O language based on C, does not support genericity. • Inheritance is also fundamental in gathering commonalities and removing duplications. • Dynamic binding replaces many complex decision structures by much shorter calls. • Assertions and the associated idea of Design by Contract avoid redundant error checking, a principal source of bloat. • The exception mechanism gets rid of some error code. If you are concerned with source size, make sure to concentrate on these architectural aspects. You should also be terse in expressing algorithms, but never skimp on keystrokes at the expense of clarity. The role of convention Most rules define a single permissible form, with no variants. The few exceptions include font use, which is governed by external considerations (what looks good in a book may not be visible on overhead transparencies), and semicolons, for which there exist two opposite schools with equally forceful arguments (although we will have a few universal rules anyway). In all other cases, in line with the introductory methodology chapter’s exhortations against wishy-washiness, the rules leave about as much room to doubt as a past due reminder from the Internal Revenue Service. The rules are rooted in a careful analysis of what works and what works less well, resulting from many years of observation; some of the rationale will appear in the discussion. Even so, some rules may appear arbitrary at first, and indeed in a few cases the decision is a matter of taste, so that reasonable persons working from the same assumptions may disagree. If you object to one of the recommended conventions, you should define your own, provided you explain it in detail and document it explicitly; but do think carefully before making such a decision, so obvious are the advantages of abiding by a universal set of rules that have been systematically applied to thousands of classes over more than ten years, and that many people know and understand
878 A SENSE OF STYLE $26.1 As noted in an earlier chapter (in the more general context of design principles),The comment was in many of the style rules were originally developed for libraries,and then found their way the introduction to into ordinary software development.In object technology,of course,all software is chapter 23. developed under the assumption that even if it is not reusable yet it might eventually be made reusable,so it is natural to apply the same style rules right from the start. Self-practice Like the design rules of the preceding chapters,the style rules which follow have been carefully applied to the many examples of this book.The reasons are obvious:one should practice what one preaches;and,more fundamentally,the rules do support clarity of thought and expression,which can only be good for a detailed presentation of the object- oriented method. The only exceptions are a few occasional departures from the rules on software text layout.These rules do not hesitate to spread texts over many lines,for example by requiring that every assertion clause have its own label.Lines are not a scarce resource on computer screens;it has been observed that with the computer age we are reversing the direction of the next-to-last revolution in written communication,the switch from papyrus rolls to page-structured books.But this text is definitely a book,structured into pages,and a constant application of the layout-related rules would have made it even bigger than it is. The cases of self-dispensation affect only two or three layout-related rules,and will be noted in their presentation below.Any exception only occurs after the first few examples of a construct in the book have applied the rules scrupulously. Such exceptions are only justified for a paper presentation.Actual software texts should apply the rules literally. Discipline and creativity It would be a mistake to protest against the rules of this chapter(and others)on the grounds that they limit developer creativity.A consistent style favors rather than hampers creativity by channeling it to where it matters.A large part of the effort of producing software is spent reading existing software and making others read what is being written. Individual vagaries benefit no one;common conventions help everyone Some of the software engineering literature of the nineteen-seventies propounded Sentence initalics the idea of "egoless programming":developing software so that it does not reflect from D.H.Brandon, “Data Processing anything of its authors'personality,thereby making developers interchangeable.Applied Organiation and to system design,this goal is clearly undesirable,even if some managers may sometimes Manpower Planning", long for it(as in this extract of a programming management book quoted by Barry Boehm: Petrocelh,1974, "...the programmer('s]creative instincts should be totally dulled to insure uniform and emphasis in original Ouoted in Boehm understandable programming",to which Boehm comments:"Given what we know about 1981,p.674. programmers and their growth motivation,such advice is a clear recipe for disaster"). What quality software requires is egoful design with egoless expression
878 A SENSE OF STYLE §26.1 As noted in an earlier chapter (in the more general context of design principles), many of the style rules were originally developed for libraries, and then found their way into ordinary software development. In object technology, of course, all software is developed under the assumption that even if it is not reusable yet it might eventually be made reusable, so it is natural to apply the same style rules right from the start. Self-practice Like the design rules of the preceding chapters, the style rules which follow have been carefully applied to the many examples of this book. The reasons are obvious: one should practice what one preaches; and, more fundamentally, the rules do support clarity of thought and expression, which can only be good for a detailed presentation of the objectoriented method. The only exceptions are a few occasional departures from the rules on software text layout. These rules do not hesitate to spread texts over many lines, for example by requiring that every assertion clause have its own label. Lines are not a scarce resource on computer screens; it has been observed that with the computer age we are reversing the direction of the next-to-last revolution in written communication, the switch from papyrus rolls to page-structured books. But this text is definitely a book, structured into pages, and a constant application of the layout-related rules would have made it even bigger than it is. The cases of self-dispensation affect only two or three layout-related rules, and will be noted in their presentation below. Any exception only occurs after the first few examples of a construct in the book have applied the rules scrupulously. Such exceptions are only justified for a paper presentation. Actual software texts should apply the rules literally. Discipline and creativity It would be a mistake to protest against the rules of this chapter (and others) on the grounds that they limit developer creativity. A consistent style favors rather than hampers creativity by channeling it to where it matters. A large part of the effort of producing software is spent reading existing software and making others read what is being written. Individual vagaries benefit no one; common conventions help everyone. Some of the software engineering literature of the nineteen-seventies propounded the idea of “egoless programming”: developing software so that it does not reflect anything of its authors’ personality, thereby making developers interchangeable. Applied to system design, this goal is clearly undesirable, even if some managers may sometimes long for it (as in this extract of a programming management book quoted by Barry Boehm: “…the programmer[‘s] creative instincts should be totally dulled to insure uniform and understandable programming”, to which Boehm comments: “Given what we know about programmers and their growth motivation, such advice is a clear recipe for disaster”). What quality software requires is egoful design with egoless expression. The comment was in the introduction to chapter 23. Sentence in italics from D.H. Brandon, “Data Processing Organization and Manpower Planning”, Petrocelli, 1974, emphasis in original. Quoted in [Boehm 1981], p. 674
$26.2 CHOOSING THE RIGHT NAMES 879 More than style standards,what would seem to require justification is the current situation of software development,with its almost total lack of style standards.In no other discipline that demands to be called "engineering"is there such room for such broad personal variations of whim and fancy.To become more professional,software development needs to regulate itself. 26.2 CHOOSING THE RIGHT NAMES The first aspect that we need to regulate is the choice of names.Feature names,in particular,will be strictly controlled for everyone's benefit. General rules What matters most is the names of classes and features which will be used extensively by the authors of classes that rely on yours. For feature and class names,use full words,not abbreviations,unless the abbreviations are widely accepted in the application domain.In a class PART describing parts in an inventory control system,call number,not num,the feature (query)giving the part number.Typing is cheap;software maintenance is expensive.An abbreviation such as usa in a Geographical Information System or copter in a flight control system,having gained an independent status as a word of its own,is of course acceptable.In addition,a few standard abbreviations have gained recognition over the years,such as PART for PARTIAL in class names such as PART COMPARABLE describing objects equipped with a partial order relation. In choosing names,aim for clarity.Do not hesitate to use several words connected by underscores,as in ANNUAL RATE,a class name,or yearly premium,a feature name. Although modern languages do not place any limit on the length of identifiers,and treat all letters as significant,name length should remain reasonable.Here the rule is not the same for classes and for features.Class names are input only occasionally (in class headers,type declarations,inheritance clauses and a few other cases)and should describe an abstraction as completely as possible,so PRODUCT OUANTITY INDEX EVALUATOR may be fine.For features,there is seldom a need for more than two or possibly three underscore-connected words.In particular,do not overqualifiy feature names.If a feature name appears too long,it is usually because it is overqualified: Composite Feature Name rule Do not include in a feature name the name of the underlying data abstraction (which should serve as the class name). The feature giving the part number in class PART should be called just number,not part number.Such over-qualification is a typical beginner's mistake;the resulting names
§26.2 CHOOSING THE RIGHT NAMES 879 More than style standards, what would seem to require justification is the current situation of software development, with its almost total lack of style standards. In no other discipline that demands to be called “engineering” is there such room for such broad personal variations of whim and fancy. To become more professional, software development needs to regulate itself. 26.2 CHOOSING THE RIGHT NAMES The first aspect that we need to regulate is the choice of names. Feature names, in particular, will be strictly controlled for everyone’s benefit. General rules What matters most is the names of classes and features which will be used extensively by the authors of classes that rely on yours. For feature and class names, use full words, not abbreviations, unless the abbreviations are widely accepted in the application domain. In a class PART describing parts in an inventory control system, call number, not num, the feature (query) giving the part number. Typing is cheap; software maintenance is expensive. An abbreviation such as usa in a Geographical Information System or copter in a flight control system, having gained an independent status as a word of its own, is of course acceptable. In addition, a few standard abbreviations have gained recognition over the years, such as PART for PARTIAL in class names such as PART_COMPARABLE describing objects equipped with a partial order relation. In choosing names, aim for clarity. Do not hesitate to use several words connected by underscores, as in ANNUAL_RATE, a class name, or yearly_premium, a feature name. Although modern languages do not place any limit on the length of identifiers, and treat all letters as significant, name length should remain reasonable. Here the rule is not the same for classes and for features. Class names are input only occasionally (in class headers, type declarations, inheritance clauses and a few other cases) and should describe an abstraction as completely as possible, so PRODUCT_QUANTITY_INDEX_ EVALUATOR may be fine. For features, there is seldom a need for more than two or possibly three underscore-connected words. In particular, do not overqualify feature names. If a feature name appears too long, it is usually because it is overqualified: The feature giving the part number in class PART should be called just number, not part_number. Such over-qualification is a typical beginner’s mistake; the resulting names Composite Feature Name rule Do not include in a feature name the name of the underlying data abstraction (which should serve as the class name)