• Bytesmiths Editions -- large, archival, fine-art photography on unusual materials
• Bytesmiths Press -- artists' services: web design/hosting, jury slides, giclee reproductions, opening announcements, brochures, etc.
• Champagne Beadworks -- handcrafted jewelry and beadwork
• Crafted By Carol -- handcrafted jewelry and beadwork
• EcoReality, an organization devoted to establishing a sustainable ecovillage
• Ecovillage Newsletter -- Diana Leafe Christian's news of her travels.
• Environmental Education Outreach -- providing environmental education worldwide.
• Gemini Gypsy -- Carole Good-Hanson's fused glass frames
• Green Chipper -- light forestry and environmental services.
• Salt Spring Island Society for Community Education -- community education on our island of 10,000.
• Veggie Van Gogh -- two artists' mobile warehouse and living quarters, petroleum-free!
• Veggiemog -- life and times of Kelly O'Toole's Unimog, running on biodiesel

Smalltalk With Style, Suzanne Skublics, Edward J. Klimas, David A. Thomas. 1996 by Prentice-Hall, Inc. 127 pages with index. $15.00 US.

Book Review by Jan Steinman and Barbara Yates

In our June 1995 column (Managing Project Documents 1 ) we mention the importance of having a style guide within your organization, but we weren't able to suggest any that you could walk into a bookstore and take home. Until now, we have pointed our clients to a 1986 OOPSLA poster paper by Roxie Rochat and an internal Allen-Bradley Smalltalk style guide by Ed Klimas as starting points. This book fills the gap, and is long overdue. It belongs with every Smalltalk project team.

Smalltalk with Style is not an "intro to Smalltalk" book. The authors provide references to several other texts for the novice to read to become acquainted with Smalltalk dialects, but this book is mostly dialect-independent, which deserves special applause.

How to Use the Book

The 126 guidelines are grouped into five chapters by topic: naming (guidelines 1-34), comments (guidelines 35-48), formatting (guidelines 49-69), reuse (guidelines 70-90), and tips (guidelines 91-126). A glossary includes basic terms, and the Preface includes some good stuff that should not be skipped.

This book should be read cover to cover the first time, rather than used strictly as a reference book with random access to guidelines via the index, because the prose leading up to the numbered guidelines is essential to grasping the authors' full meaning for the guideline. The examples following most guidelines are required reading too! Finally, there are boxed notes or "tips" sprinkled throughout the chapters that contain very helpful information.

A recent thread in comp.lang.smalltalk about Smalltalk code formatting shows how religious an issue such a topic is; the same is true about a lot of the guidelines in this book. You'll find experienced Smalltalkers have strong opinions both favoring and opposing some of these guidelines. This book's value is not in dictating a standard to be followed, but in collecting in one place the combined wisdom of many Smalltalk programmers who have been writing and reading Smalltalk code for over a decade.

Some guidelines may appear deceptively obvious. You may ask yourself "who would think of doing such a thing?" when reading some of the bad examples. Even simple guidelines that experienced Smalltalkers take for granted may be novel ideas to brand-new Smalltalkers, and our experience in helping organizations adopt Smalltalk shows that not a single guideline in this book is too obvious.

Some of the guidelines will be mis-applied by novices without careful attention to their accompanying examples. One such case is the recommendation to use parentheses to improve readability. Some novices will use this as an excuse to avoid learning the simple Smalltalk precedence rules, but the examples clearly show use and abuse of parentheses. Don't expect this to be a Smalltalk programming instructional manual -- it isn't intended to be.

Diplomacy vs. Dogmatism

The writers are not overly dogmatic, recognizing that certain issues are largely a matter of individual taste. For example, on page 41 they state "There is no absolute way to indent and align Smalltalk code. It is more important to be consistent within your code and, when changing someone else's code, to be consistent with their code."

One unfortunate effect of this diplomacy is that in places the book appears to bend over backwards to avoid stating a preference -- there are eight code fragments to illustrate the alignment of brackets for Guideline 61, which then states "Choose one way to align brackets in blocks and use it consistently. " This statement of a guideline backed up by alternate ways to apply it illustrates one of the points made in the introduction: "This book should be used as the first draft for your own guide to good Smalltalk style... The best guidelines are those that people want to follow because they appreciate the benefit. Blind enforcement of a matter that is of personal taste is not in the interest of the project as a whole. "

Although the book is dialect-independent for the most part, we did notice guidelines that are unnecessary in many Smalltalk development environments. For example, a line length limit for source code is suggested, but is a nuiscance in the majority of Smalltalk environments that have re-sizeable, auto-wrapping code windows. Rather than attempting complete dialect neutrality, it would have been nice if the authors had pointed out the dialect implications of such guidelines.

This suggests the need for additional style rules in your organization that are dialect and toolset dependent, for example, specific naming conventions for ENVY applications and version names. Keep in mind (as the authors point out), that this book is a starting place for your organization, not a coding style bible to be adopted as-is.

For us, the most enjoyable section of the book is chapter 5: Tips, Tricks, and Traps . Unlike the guidelines in the preceding sections, which are open to argument and sometimes controversial, these guidelines are mostly universally accepted and of particular importance to beginning Smalltalkers. Some of these guidelines are meant to help you avoid some of the "classic Smalltalk bugs" such as modifying a collection while iterating over it, or forgetting to send yourself after a succession of cascaded add: messages to a new collection.

Regrettably, some guidelines in this section cover important topics such as testing in a superficial way. Perhaps it is more important that something be said on these topics, albeit very little, with further guidelines in these areas left up to the readers to develop. Once again, this book is a template for you to complete, not an all-inclusive tome.

Improvements

Although we unreservedly recommend this book, we have some wishes for a second edition. It could benefit from the eye of a professional book designer, since the layout is a bit unapproachable and difficult to scan, with numerous widows and orphans and a fussy indentation scheme. (Contrast this to an absolutely gorgeous book that is similar in concept: 201 Principles of Software Development , Alan M. Davis, 1995, McGraw-Hill, which also should be on everyone's shelf.)

There were also a very few outright inaccuracies, such as the glossary definition of a class instance variable. (Class instance variable are not shared by instances of the class.)

Also strangely lacking (given two of the authors are at OTI, makers of ENVY) are guidelines regarding the temporal aspects of development, which is in many ways unique to Smalltalk. Certainly more could be said on this topic than "Guideline 120: Avoid modifying the existing behavior of base system classes ," without turning into an ENVY ad!

Many of the guidelines lack context and background. This is probably necessary to keep it from ballooning into a general-purpose Smalltalk how-to book, but the lack of "why" behind some of these may cause unnecessary resistance in following them.

It should be taken as a tribute to this book that our criticism can be largely boiled down to "more, please!"

Excerpts

To give you an idea of what the book is like, here are some of our favorite guidelines, and some that we found most controversial.

• Guideline 26: Do not use the same temporary variable name within a scope for more than one purpose. This is one of those "motherhood" guidelines that should be obvious, but we see it violated every day, particularly by new converts to Smalltalk from C or FORTRAN.
• Guideline 40: Maintain the method comments with as much care as the source code and keep them synchronized. Amen! This is the "constant accuracy" principle of documentation we describe in our June 95 column.
• Guideline 104: Test classes as they are developed. and Guideline 105: Test components as they are integrated. Testing is one of the great lies: "The check is in the mail," "I'll still love you in the morning," and "It's done (except for testing)." Expect testing to take on renewed importance as many large, first-generation Smalltalk projects enter their second iteration.

More controversial is the example under guideline 59 shown as a "bad choice" because "although the Blue Book... uses this style, most programmers [keep the left bracket on the line with whileTrue:]":

    [number <= 100] whileTrue:
        ["more code here
        and here"].

This is an example of the hidden dialect bias we would have preferred was explicit. The built-in VisualWorks formatter makes your code look similar to this "bad" example, and "most programmers" with a VisualWorks, Objectworks, or Smalltalk-80 background are likely to code in the "bad" style -- it should not be discouraged in such shops.

We also find many of the bracketing and indenting styles would be alien (or go missing) to someone whose only Smalltalk exposure was a Smalltalk-80-family image. For example, an important missing Smalltalk-80 guideline is to not line up columns of text with tabs, since the use of different fonts will obliterate the horizontal spacing.

Guideline 64: Separate cascaded long key word messages with a blank line or further indent subsequent keywords after the first if the message has multiple keywords. Example: [complies with guideline]

anOrderedCollection
        replaceFrom: 2
        to: 3
        with: #(a b c d e f g)
        startingAt: 3;
 
        replaceFrom: 7
        to: 8
        with: #(a b c d e f g)
        startingAt: 5.

Vertical white space is usually precious resource, and we prefer guidelines that conserve it over guidelines that tend to make you scroll. This example also shows the "narrow, non-wrapping window" dialect bias, and a Smalltalk-80 programmer would probably keep each message on the same line, with no extra whitespace.

Guideline 119 regarding lazy initialization does not address its real value: providing state sequence independence. Better would have been a brief discussion of base and derived state and a guideline to "eagerly" initialize base state, while "lazily" initializing derived state, but this once again treads the fine line between a style guide and a design guide.

Conclusion

Before looking at the book, we asked ourselves some questions that we've heard from novices. Happily, this book answered all that strictly concerned style, but missed some that sit on the line between style and design:

• Should I always write instance methods and create a single instance of a class, rather than treat the class as a global and write only class methods?
• What kind of behavior normally belongs on the class side?
• How do I decide which type of collection to use in my application -- anArray, anOrderedCollection, something else?

Admittedly these are not really style questions, but this book does cross the line from style to programming and process guidelines at various times.

We don't envy the authors their task of choosing what to put in and what to leave out. All in all they did an admirable job, and it is with pleasure that we look forward to reading the "revised and enlarged" edition which will surely come in the future.

At least one copy of this book belongs with every Smalltalk project team!

Go to the previous column in the series, or the next column in the series.