I’ve been reading through a lot of sample code lately, and I’ve noticed a number of frustrating and annoying trends that repeat often enough to rise to the level of antipatterns. I list them here not simply to gripe about them, but to point out that they are bad and why, so that perhaps in the future they will become less common.

Antipattern 1: The “Kitchen Sink” example

Description: Instead of creating a small, self-contained, specific example to illustrate how to use a specific API or technique, the author writes a single gigantic example that includes absolutely everything, and then refers to pieces of it when illustrating specific topics.

Example: The “Java Pet Store” example used for J2EE.

Why it is bad: Typically, these apps make use of multiple APIs, each of which has its own configuration requirements and preconditions. The net result is that all of these APIs end up as a single tangled mess, and trying to figure out what you need to do to make a single small portion of the example work in isolation is a long and frustrating experience.

What to do instead: Instead of a single mega-example, write a set of small and self-contained examples, each of which is specific to the point you’re trying to illustrate. If you like, you can knit these small examples together into a larger enterprise app later on. And since there is no cross-module coupling, the resulting app will be a better piece of software engineering. Everybody wins!

 Antipattern 2: The “No Assembly Required” example

Description: The author provides a .jar or .zip file containing the example, already configured and ready to run, but neglects to discuss large elements of the application’s functionality.

Example: IBM’s technology quickstart for JPA. It goes through the process of creating a JPA project in painful detail, which is a good thing. But at the last step, instead of stepping you through a simple piece of code to call the JPAs, they direct you to import a full-featured Java Server Faces (JSF) application, which uses the beans. The JSF code is largely auto-generated and the portions of it that actually use the JPA objects you created are buried deep within it.

Why it is bad:After you complete the example, you still don’t know how to use the technology. You know how to use a piece of it, but you can’t sit down at a blank screen, create one from scratch, and use it. So you need to go off and find another tutorial to fill in the gaps.

What to do instead: Instead of dazzling the user with advanced functionality and pretty user interfaces, focus on creating a small, self-contained example that shows the basic operations. Show me how to connect to your server, create an object, read an object, update an object, and delete an object, and I’m happy.

Antipattern 3: the “point and click and click and click and click and click” example

Description: A simple “hello world” example includes 10-20 pages of screenshots of wizards and configuration steps that have little or nothing to do with the core functionality.

Example:Too many to name

Why it is bad: First, point-and-click configuration itself is an antipattern, because you can’t automate it. Second, it’s tedious and error-prone to go through screen after screen, filling in fields and checkboxes by coping from the article. Third, a lot of systems don’t have very good undo capabilities, so if you make a mistake, you have to trash your work and start over.

What to do instead: Pity the poor author. Sometimes the only way to configure a product is via point-and-click, and sometimes the process is so cumbersome that it really does require 20 pages of screenshots to do “Hello World.” Blame the guys that wrote the product. The author’s only hope when faced with this is to be very organized and clear in presentation, and preferably to separate out the “writing code” portions of the activity from the “configuring the system” portions. For example, start with an architectural overview that lets the reader know where all the widgets fit in the big picture, then have a section where they write the widgets, and close with a section where you bundle them up and do the necessary configuration to make them run.