Effective Java, Thoughtworks Anthology, Javascript: The Good Parts

This article appears in slightly different form in the September/October 2008 issue of IEEE Micro © 2008 IEEE.

Software Development Patterns

This time I look at three books about programming. None of them has the word "patterns" in its title, and none of them claims to deal with patterns or best practices, but that is what they are all about.

Effective Java, 2d ed by Joshua Block (Addison-Wesley, Upper Saddle River NJ, 2008, 368pp, ISBN 978-0-321-35668-0, $49.99)

When I reviewed the first edition of this book (Micro Review, July/Aug 2002), I had never met Josh Bloch. Several years later, however, I was visiting the Google booth at JavaOne, when Josh came up to me and told me that my review had launched his book. He believed this because when my review appeared, his book had already been out for a year with modest sales, and his sales then increased substantially. I don't believe that my review had much to do with it. The book has a lot of substance, and it takes time for people to digest it and spread the word. Nonetheless, I recently took advantage of his gratitude to persude him to give me a copy of the new edition.

The first edition contains 57 short essays, called items. The new edition has 78 items. A few of the original items have disappeared, and Josh has added items to reflect the important changes to Java since 2001. He was a major player on the teams that developed generics, enum types, annotations, autoboxing, and the Java 5 for-each loop and concurrency library. 

In 2004, Josh moved from Sun to Google, where he continues to guide the evolution of the language but now also develops Java libraries that use the new features. Thus he knows Java both as a language designer and a language user. There is probably no other person who could have written this book with the same degree of insight and experience.

If you ever have a chance to hear Josh talk, don't miss it. He is an excellent teacher, because he explains complex points clearly. That talent shines through the pages of this book as well. The items that Josh discusses are quite complex, even abstruse. Yet any experienced Java programmer can understand them.

My review of the first edition highlights many good points that are still good in this one. What I concluded about the first edition remains true of this one. Every bit of this book is essential for Java designers. Reading this book before you start delivering products can easily repay its cost thousands of times.

The ThoughtWorks Anthology -- Essays on Software Technology and Innovation by members of the ThoughtWorks staff (Pragmatic Bookshelf, Raleigh NC, 2008, 234pp, ISBN 978-1-934356-14-2, $38.95)

ThoughtWorks is a software development firm that specializes in fighting software bloat. To this end they have developed techniques for programming, building, testing, and delivering applications efficiently. The essays in this book present several of these techniques.

ThoughtWorks's founder, Roy Singham lays out his vision in the first essay. He talks about "the last mile" of putting a system into production. The expression "the last mile" comes from the telecommunications industry. The high speed backbone of the global internet slows down when it reaches the "last mile" of copper wire that brings bits to and from most individual customers. People have been talking about this problem for decades, but customers have seen few improvements.

For Singham, the last mile starts when the software meets all of its functional requirements. It ends when it is in place, delivering value to the customer. Development teams can bring a project to a conclusion rapidly and efficiently because of their tools and methodologies. Customers then begin a long, slow, expensive process. They must ensure that the new software can handle the expected workload, work well with other systems, interact with existing data without corrupting it, and protect against all sorts of unauthorized use or attacks.

Currently, developers derive functional requirements from end users who, ideally, have continual contact with the developers throughout the project. Singham suggests adding the last mile tasks to the functional requirements and involving the last mile stakeholders in the project from its inception. This should lead developers to automate much of the last mile process, just as they routinely automate builds and testing. 

In telecommunications, the Holy Grail of the last mile problem is a means by which the internet can reach any customer at full speed (for example, fiber to the home). For software, Singham sees the Holy Grail as versionless software, a means by which developers can add features directly to production systems "on the fly," without fear of unintended consequences. Neither of these visions will come to pass any time soon.

Twelve more essays round out this book. They deal with programming, managing development, maintaining web applications and service oriented architectures, and building and testing systems. Having worked with large, convoluted Ant scripts, I especially appreciate Julian Simpson's essay on refactoring techniques for such files.

In the 1970s I worked with the late Rudolph Langer, who built a number of special purpose languages, usually on top of macro assembly languages. One of these, for example, facilitated designing pinball machines. Another made it easy to design optical forms to enable users to enter data visually. Nowadays we might call these domain specific languages (DSLs). Martin Fowler's essay explains how to use Ruby to create a DSL.

One of my favorite essays is Jeff Bay's "Object Calisthenics."  He proposes an exercise in which you must write a 1000 line Java program using the following extremely strict coding standards:

• Use only one level of indentation per method.
• Don't use the else keyword.
• Wrap all primitives and strings.
• Use only one dot per statement.
• Don't abbreviate.
• Keep all entities small.
• Limit classes to two instance variables.
• Use first class collections.
• Don't use getters, setters, or properties.

Bay explains the points that he intends this exercise to make. He wants you to encapsulate data, use polymorphism properly, avoid duplication, and appropriately model the problem that you want the code to solve. 

Like most books from the Pragmatic Bookshelf, this one is full of good practical advice. If you develop software, this one should be on your bookshelf.

JavaScript: The Good Parts -- Unearthing the Excellence in JavaScript by Douglas Crockford (O'Reilly, Sebastopol CA, 2008, 170pp, ISBN 978-0-596-51774-8, www.oreilly.com, $29.99)

Douglas Cockford is a JavaScript architect at Yahoo, where he introduced and maintains the JavaScript object notation (JSON) format. He is deeply steeped in the intricacies of the JavaScript language. The target audience for this book consists of highly experienced software designers and architects who are probably working on Ajax applications. If you do a little JavaScript programming to spruce up your website and are looking for a few tips and tricks, this is not the book for you.

Early browsers used Java applets, but this technology did not catch on. JavaScript went, in too short a time, from a rough draft of a language to the main language recognized by browsers. Subsequent revisions have added features, but the basic language design remains unpolished. Cockford refers to JavaScript as a "beautiful, elegant, highly expressive language that is buried under a steaming pile of good intentions and blunders."

The part that Cockford considers beautiful is what he calls Lisp in C's clothing. By this he means that at heart JavaScript is a functional language like Lisp or Scheme, but its syntax resembles that of C. JavaScript has objects but not classes, which confuses many casual JavaScript programmers. You can create objects from prototypes, but you can also freely add attributes and methods. You can also define objects as literals, simply by listing their attributes and methods.

Cockford sets out to show you how to create JavaScript programs that use the parts of the language that he likes and avoid the parts he considers bad. Unfortunately, you can't avoid all of the bad parts (for example, global variables, the lack of block scoping, the poor way it handles Unicode). 

Cockford's explanations of how to avoid the bad parts entail sophisticated programming. His examples require careful reading, and real mastery probably takes a lot of practice. Cockford characterizes the book as follows:

"This book is small, but it is dense. There is a lot of material packed into it. Don't be discouraged if it takes multiple readings to get it."

Excluding the appendixes and the index, the book is 100 pages long. You probably won't read it in one sitting, but it will repay your effort. It doesn't spend much time explaining the bad parts. If you want to use those, Cockford says, read any of the other JavaScript books.

If you are an experienced programmer familiar with many programming languages but forced to do serious development in JavaScript, this book may save you an enormous amount of trouble.

Adobe for Technical Communicators, Switching to the Mac

This article appears in slightly different form in the March/April 2008 issue of IEEE Micro © 2008 IEEE.

This time I talk about two subjects that are not the way they once were and may change again tomorrow.

Adobe Technical Communication Suite (Adobe, San Jose CA, www.adobe.com, $1599.00)

Fifteen years ago, the tools of the technical communicator's trade came from many companies. The most important tool for creating technical manuals was FrameMaker from Frame Technology. For newsletters, marketing pieces, and other short documents, writers also used the more agile PageMaker, a tool for composing pages, from a company named Aldus. RoboHelp, from Blue Sky (later called eHelp) emerged as the tool of choice for creating online help systems. When web browsing became popular, Macromedia brought out DreamWeaver, the HTML editor of choice. Macromedia also developed Flash technology, one of the simplest ways to add animation to online content.

Starting in the early 1980s, a company called Adobe invented Postscript, the display language that now sits inside virtually every laser printer. They also developed the premier tools for manipulating vector and bitmapped graphics: Illustrator and Photoshop. Postscript is great for the insides of printers, but not so good for interchange and multimedia, so in the early 1990s, Adobe developed Portable Document Format (PDF). More than 90% of personal computers have software to read PDF files.

When many companies serve the same customers with different products, there is usually one outcome -- one or more companies grow by absorbing the others, and soon the customers have a small number of full service suppliers.  Adobe now owns all of the products mentioned earlier in this column. Only Microsoft has a plausible claim to being a competitor.

Having accumulated a set of products for the same audience, Adobe has taken the added step of making them work together smoothly. The Technical Communication Suite (TCS) consists of FrameMaker, RoboHelp, Captivate, and Acrobat 3D. If you buy them as the TCS, they work more efficiently together, and cost less, than if you buy them separately. 

For technical communicators, FrameMaker and RoboHelp are the heart of the TCS. Captivate, which simplifies creating Flash-based demonstrations and training, may become more popular as buyers of the TCS learn how to use it. Acrobat 3D, for most technical communicators, is essentially the same as Acrobat, but with a flashy new feature (embedded 3D graphics) that most of them will never use.

FrameMaker is the tool most technical communicators choose to create books. It manages the chapters, appendixes, indexes, and so forth in a structure called a book file. It provides ways to maintain consistent styles and formats throughout the final document. It provides a facility for including some text conditionally, based on attribute values applied to the document at publication time. Up until the TCS, FrameMaker worked with a product called WebWorks Publisher to produce HTML output from the same source files. In the TCS, RoboHelp provides HTML publishing capabilities for FrameMaker.

I first reviewed FrameMaker in the May/June 1993 Micro Review. Unlike the current version, FrameMaker 3.0 worked essentially identically on both Macintosh and PC, as well as on the Unix systems for which Frame Technology had originally designed it. FrameMaker 8 and the TCS work only in a Microsoft Windows (XP or Vista) environment. Adobe has given no indication that they will ever support this product in the Macintosh environment. On the other hand, FrameMaker 8 has a variety of new or improved features, when compared with FrameMaker 7.2:

• Change tracking -- at last!
  
• A tabbed view to facilitate working with many source files simultaneously
  
• Improved Unicode support
  
• Spelling and hyphenation dictionaries for 30 languages
  
• Better XML support (but still no DTDs or schemas)
  
• Support for Darwin Information Typing Architecture (DITA)
  
• Integration of rich media (for example, Flash or 3D graphics)
  
• An updated Frame Developer's Kit (FDK)
  

Like any new version, FrameMaker 8 has given me a few unpleasant surprises. I encountered, as others have reported, occasional crashes or failures to complete requested operations. However, I did two serious projects with FrameMaker 8 and was able to get past the occasional problems to produce correct PDF output.

Most technical communicators who produce online help use RoboHelp to do so. It facilitates building a body of information units called topics. It provides ways to maintain consistent styles and formats, and it manages all the ways end users can navigate to and among the topics. There are many standard formats for online help -- nowadays all based on HTML -- and RoboHelp supports all of them from a single source.  

I first reviewed RoboHelp (version 2.6) in the Sept/Oct 1994 Micro Review. Over the succeeding years, new RoboHelp versions came out much too frequenty, leading to internal problems in the product. According to Mike Hamilton, a former key eHelp employee, Adobe inherited a code base in December 2005 that needed massive reorganizing and bug fixes. Another problem with RoboHelp was its output of a proprietary form of HTML, based on the notorious tags. Adobe began to attack these problems with RoboHelp 6. They have now brought out RoboHelp 7 as part of the TCS.

In the TCS, RoboHelp works well with FrameMaker. Like FrameMaker, RoboHelp provides styles, variables and conditional text. You can define a mapping between FrameMaker's sytles, variables, and conditions and RoboHelp's. The mapping facilitates importing FrameMaker output into RoboHelp. You can import FrameMaker files into RoboHelp by reference, so that RoboHelp receives subsequent changes to the FrameMaker file, or you can import as a copy, so that subsequent changes to the FrameMaker file do not affect the RoboHelp version.

RoboHelp can also import files of a variety of formats, including Microsoft Word 2007, as well as earlier Word formats. It converts all imported files into HTML and provides a built-in HTML editor for manipulating them.

RoboHelp projects generally contain large numbers of files, sometimes worked on simultaneously by more than one person. RoboHelp comes with a source control facility that provides locking, history, and a means to compare versions. 

Captivate is new to most technical communicators. It provides ways to create simulations (annotated animated screen captures) and training materials, including quizzes. Captivate produces Flash output, so that file sizes are relatively small. It can even import PowerPoint presentations and convert them to Flash.

Acrobat is an essential tool for technical communicators. It has many quirks, and there are gurus to help you deal with them (see Micro Review Sept/Oct 2004). It provides a way of publishing reasonably sized files representing printed manuals. It provides a variety of means for reviewing and annotating documentation. 

In the TCS, Acrobat enables you to embed three dimensional figures -- the output of common computer-aided design programs -- in PDF files. Readers can then manipulate the figures without special software. You can also embed Flash, sound, and other multi-media formats. 

The way I use Acrobat, I've noticed little difference since moving to the TCS. My one complaint is that printing generally takes longer. There are some documents I print routinely that used to come out quickly with my old version of Acrobat but now take so long that the printer manager sends back an error message saying that the document failed to print. If I ignore the message, the document eventually prints. I've only tried this with one printer -- my ten-year-old HP LaserJet 4000 -- so perhaps it's not a general problem.

Adobe has made it easy for technical communicators to adopt the TCS. The bundle price essentially gives you some components at no cost. Adobe also offers generous discounts to owners of earlier versions of any of the components. It also offers student discounts. 

By bundling the products of the TCS, Adobe makes it less likely that a competitor to any of these products will become a new standard. An example of such a competing product is Flare, from MadCap Software. When Adobe acquired Macromedia, which had recently acquired eHelp, members of the RoboHelp team left Adobe to found MadCap. This gives MadCap Flare immediate credibility among technical communicators. Adobe's bundling of RoboHelp into the TCS, however, creates a large barrier to a successful challenge to RoboHelp by Flare. 

If you produce technical documentation, you probably already use FrameMaker or RoboHelp. You should take advantage of this package to obtain the benefits of the greater integration. It will also give you Captivate and the 3D features of Acrobat, essentially free.

Switching to the Mac, Leopard Edition: The Missing Manual by David Pogue (O'Reilly, Sebastopol CA, 2008, 604pp, ISBN 978-0-596-51412-9, www.oreilly.com, $29.99)

In 1984 I got my first Apple Macintosh computer, and I used Macs almost exclusively until the early 1990s, when Windows 3.1 became a serious competitor. Gradually I switched almost entirely to PCs. I haven't done any serious work with a Mac in many years.

Recently I had occasion to borrow a Mac to review some Mac software. I found the experience extremely frustrating. I know that a Mac can do essentially everything a PC can do, but they do it differently enough that I felt like a beginner. It reminded me of times when I've tried to express myself in a language I don't know very well. I know what I want to say, but I don't know how to say it in that language. My mind races ahead, but my tongue cannot follow. This is the problem that David Pogue attacks first. The first four chapters tell you how to accomplish things on a Mac that you already know how to do on a PC.

If you're not just visiting, but actually emigrating from the PC to the Mac, there is still a lot more to do. You need to move your files and get used to a whole new set of application programs. While some programs work exactly the same in both environments, you may find yourself using a different browser or mail program. Many programs work almost exactly the same. Pogue lists the tiny differences to be aware of in dozens of common programs.

The remainder of the book is not so much about switching as about understanding how the Mac OS X operating system works. For example, you probably have a limited view of how networking or system preferences work in the Windows environment. Pogue explains the somewhat more comprehensible Mac versions of these subjects.

If you are a PC user, and you need to use a Mac or are considering moving permanently to a Mac, this is an essential book. Don't leave your PC without it.