Style Case Studies: Index Tables - Solution to Item 34: Dissecting Index Tables
(Page 2 of 6 )
Clarity: A Short Sermon
1. Who benefits from clear, understandable code?
In short, just about everyone benefits.
First, clear code is easier to follow while debugging and, for that matter, is less likely to have as many bugs in the first place, so writing clean code makes your own life easier even in the very short term. (For a case in point, see the discussion surrounding Example 27-2 in Item 27.) Further, when you return to the code a month or a year later—as you surely will if the code is any good and is actually being used—it’s much easier to pick it up again and understand what’s going on. Most programmers find keeping full details of code in their heads difficult for even a few weeks, especially after having moved on to other work; after a few months or even a few years, it’s too easy to go back to your own code and imagine it was written by a stranger—albeit a stranger who curiously happened to follow your personal coding style.
But enough about selfishness. Let’s turn to altruism: Those who have to maintain your code also benefit from clarity and readability. After all, to maintain code well one must first grok the code. “To grok,” as coined by Robert Heinlein, means to comprehend deeply and fully; in this case, that includes understanding the internal workings of the code itself, as well as its side effects and interactions with other subsystems. It is altogether too easy to introduce new errors when changing code one does not fully understand. Code that is clear and understandable is easier to grok, and therefore, fixes to such code become less fragile, less risky, less likely to have unintended side effects.
Most important, however, your end users benefit from clear and understandable code for all these reasons: Such code is likely to have had fewer initial bugs in the first place, and it’s likely to have been maintained more correctly without as many new bugs being introduced.
Guideline: By default, prefer to write for clarity and correctness first.
Dissecting Index Tables
2. The following code presents an interesting and genuinely useful idiom for creating index tables into existing containers. For a more detailed explanation, see the original article [Hicks00].
Critique this code and identify:
a) Mechanical errors, such as invalid syntax or nonportable conventions
b) Stylistic improvements that would improve code clarity, reusability, and maintainability.
Again, let me repeat that which bears repeating: This code presents an interesting and genuinely useful idiom. I’ve frequently found it necessary to access the same container in different ways, such as using different sort orders. For this reason it can be useful indeed to have one principal container that holds the data (for example, a vector<Employee>) and secondary containers of iterators into the main container that support variant access methods (for example, a set<vector<Employee>::iterator, Funct> where Funct is a functor that compares Employee objects indirectly, yielding a different ordering than the order in which the objects are physically stored in the vector).
Having said that, style matters too. The original author has kindly allowed me to use his code as a case in point, and I’m not trying to pick on him here; I’m just adopting the technique, pioneered long ago by such luminaries as P. J. Plauger, of expounding coding style guidelines via the dissection and critique of published code. I’ve critiqued other published material before and have had other people critique my own, and I’m positive that further dissections will no doubt follow.
Having said all that, let’s see what we might be able to improve in this particular piece of code.
 This chapter is from Exceptional C++ Style, by Herb Sutter (ISBN 0201760428, copyright 2005. All rights reserved. It is reprinted with permission from Addison-Wesley Professional). Check it out at your favorite bookstore today.
Buy this book now. |
Next: Correcting Mechanical Errors >>
More Code Examples Articles
More By Addison-Wesley/Prentice Hall PTR
