Home · Book Reports · 2017 · The Pragmatic Programmer

designates my notes. / designates important.

Thoughts

A “classic” from 1999. Lots of interesting “roots” of some now commonly known programming principles. I was particularly gleeful to hear the lauding of plain text files - my preferred way of storing almost everything. I think even JSON is mentioned alongside the more ubiquitous XML in 1999.

Source control, particularly since git/github, is now defacto. The authors were way ahead of this fact. Similarly they mention something dangerously similar to test driven design, modern buzzwords sure, but still a great way to work. There are also a lot of general how to deal with day-to-day problems programmers face, like customer spec sheets, deadlines, and communication.

Interesting and breezy read, would recommend as light reading to any programmer.

Table of Contents

• Chapter 1 - A Pragmatic Philosophy
• Chapter 2 - A Pragmatic Approach
• Chapter 3 - The Basic Tools
• Chapter 4 - Pragmatic Paranoia
• Chapter 5 - Bend or Break
• Chapter 6 - While You Are Coding
• Chapter 7 - Before the Project
• Chapter 8 - Pragmatic Projects
• Appendix A: Resource

· Chapter 1 - A Pragmatic Philosophy

page 33:

• Striving to better, oft we mar what’s well. King Lear 1.4

page 37:

• Invest Regularly in Your Knowledge Portfolio

· Chapter 2 - A Pragmatic Approach

page 49:

• maintenance is not a discrete activity, but a routine part of the entire development process.

• Tip 11: DRY—Don’t Repeat Yourself

page 54:

• The use of accessor functions ties in with Meyer’s Uniform Access principle |Mey97b], which states that “All services offered by a module should be available through a uniform notation, which does not betray whether they are Implemented through storage or through computation.”

page 55:

• Have some kind of forum/BBS for developers.

page 57:

• Two or more things are orthogonal if changes in one do not affect any of the others. In a well-designed system, the database code will be orthogonal to the user interface: you can change the interface without affecting the database, and swap databases without changing the interface.

page 59:

• It is easier to write relatively small, self-contained components than a single large block of code. Simple components can be designed, coded, unit tested, and then forgotten

page 60:

• Sometimes these components are organized into layers, each providing a level of abstraction. This layered approach is a powerful way to design orthogonal systems. Because each layer uses only the abstractions provided by the layers below it, you have great flexibility in changing underlying implementations without affecting code. Layering also reduces the risk of runaway dependencies between modules. You’ll often see layering expressed in diagrams such as

page 61:

• “It’s Just a View”, talks about writing decoupled code using the Model-View-Controller (MVC) paradigm

page 62:

• Also ask yourself how decoupled your design is from changes in the real world. Are you using a telephone number as a customer identifier? What happens when the phone company reassigns area codes? Don’t rely on the properties of things you can’t control.

page 64:

• Get into the habit of being constantly critical of your code. Look for any opportunities to reorganize it to improve its structure and orthogonality.

• we suggest that every module have its own unit test built into its code, and that these tests be performed automatically as part of the regular build process

page 66:

• Consider the difference between large GUI-oriented tools typically found on Windows systems and small but combinable command line utilities used at shell prompts. Which set is more orthogonal, and why? Which is easier to use for exactly the purpose for which it was intended? Which set is easier to combine with other tools to meet new challenges?

page 70:

• Tip 14: There Are No Final Decisions

page 74:

• Use basic “tracer” code to get functionality proven, then flesh it out.

• The conventional alternative is a kind of heavy engineering approach: code is divided into modules, which are coded in a vacuum. Modules are combined into subassemblies, which are then further combined, until one day you have a complete application. Only then can the application as a whole be presented to the user and tested.

• The most daunting piece of paper is the one with nothing written on it.

page 76:

• Prototyping generates disposable code. Tracer code is lean but complete, and forms part of the skeleton of the final system. Think of prototyping as the reconnaissance and intelligence gathering that takes place before a single tracer bullet is fired.

page 78:

• Tip 16: Prototype to Learn

page 85:

• BNF, or Backus-Naur Form, lets you specify context-free grammars recursively. Any good book on compiler construction or parsing will cover BNF in (exhaustive) detail.

· Chapter 3 - The Basic Tools

page 98:

• we believe that the best format for storing knowledge persistently is plain text. With plain text, we give ourselves the ability to manipulate knowledge, both manually and programmatically, using virtually every tool at our disposal.

page 99:

• Tip 20: Keep Knowledge in Plain Text

page 100:

• Human-readable forms of data, and self-describing data, will outlive all other forms of data and the applications that created them. Period.

page 111:

page 114:

• Progress, far from consisting in change, depends on retentiveness. Those who cannot remember the past are condemned to repeat it. -George Santayana, Life of Reason

page 115:

• Tip 23: Always Use Source Code Control

• Always. Even if you are a single-person team on a one-week project. Even if it’s a “throw-away” prototype. Even if the stuff you’re working on isn’t source code. Make sure that everything is under source code control—documentation, phone number lists, memos to vendors, makefiles, build and release procedures, that little shell script that burns the CD master—everything. We routinely use source code control on just about everything we type (including the text of this book). Even if we’re not working on a project, our day-to-day work is secured in a repository.

page 125:

• if you see hoof prints, think horses—not zebras. The OS is probably not broken. And the database is probably just fine.

page 126:

• Tip 27: Don’t Assume It—Prove It

page 137:

• All this talk of active this and passive that may leave you with the impression that code generators are complex beasts. They needn’t be. Normally the most complex part is the parser, which analyzes the input file. Keep the input format simple, and the code generator becomes simple.

· Chapter 4 - Pragmatic Paranoia

page 139:

• Tip 30: You Can’t Write Perfect Software

page 144:

• Liskov Substitution Principle [Lis88]: Subclasses must be usable through the base class interface without the need for the user to know the difference.

page 146:

• Preprocessors

• For C and C++, you may want to investigate Nana [URL 18]. Nana doesn’t handle inheritance, but it does use the debugger at runtime to monitor assertions in a novel way.

page 147:

• Assert and crash early.

page 148:

• Loops are subject to the banana problem (I know how to spell “banana,” but I don’t know when to stop), fencepost errors (not knowing whether to count the fenceposts or the spaces between them), and the ubiquitous “off by one” error [URL 52].

page 153:

• Have you noticed that sometimes other people can detect that things aren’t well with you before you’re aware of the problem yourself? It’s the same with other people’s code. If something is starting to go awry with one of our programs, sometimes it is a library routine that catches it first.

• All errors give you information.

• Tip 32: Crash Early

page 156:

• There is a luxury in self-reproach. When we blame ourselves we feel no one else has a right to blame us. -Oscar Wilde, The Picture of Dorian Gray

• Tip 33: If It Can’t Happen, Use Assertions to Ensure That It Won’t

page 169:

• Deallocate resources in the opposite order to that in which you allocate them. That way you won’t orphan resources if one resource contains references to another.

· Chapter 5 - Bend or Break

page 182:

page 183:

• Tip 36: Minimize Coupling Between Modules (Law of Demeter)

• As with any technique, you must balance the pros and cons for your particular application. In database schema design it is common practice to “denormalize” the schema for a performance improvement: to violate the rules of normalization in exchange for speed. A similar tradeoff can be made here as well. In fact, by reversing the Law of Demeter and tightly coupling several modules, you may realize an important performance gain. As long as it is well known and acceptable for those modules to be coupled, your design is fine.

page 187:

• First, we want to make our systems highly configurable. Not just things such as screen colors and prompt text, but deeply ingrained items such as the choice of algorithms, database products, middleware technology, and user-interface style. These items should be implemented as configuration options, not through integration or engineering.

• Tip 37: Configure, Don’t Integrate

page 193:

• On many projects, we need to model and analyze the users’ workflows as part of requirements analysis. We’d like to find out what can happen at the same time, and what must happen in a strict order. One way to do this is to capture their description of workflow using a notation such as the UML activity diagram.

page 203:

• Tip 42: Separate Views from Models

page 204:

• Model. The abstract data model representing the target object. The model has no direct knowledge of any views or controllers.

• View. A way to interpret the model. It subscribes to changes in the model and logical events from the controller.

• Controller. A way to control the view and provide the model with new data. It publishes events to both the model and the view.

page 210:

• Tip 43: Use Blackboards to Coordinate Workflow

· Chapter 6 - While You Are Coding

page 215:

• Document your assumptions.

• test your assumptions as well.

• Don’t be a slave to history. Don’t let existing code dictate future code. All code can be replaced if it is no longer appropriate. Even within one program, don’t let what you’ve already done constrain what you do next—be ready to refactor (see Refactoring).

page 219:

• Sometimes we come up with fairly complex O() functions, but because the highest-order term will dominate the value as n increases, the convention is to remove all low-order terms, and not to bother showing any constant multiplying factors. O(n /2+ 3n) is the same as O(n /2), which is equivalent to O(n ). This is actually a weakness of the O() notation—one O(n ) algorithm may be 1,000 times faster than another O(n ) algorithm, but you won’t know it from the notation.

page 221:

• The O() notation doesn’t apply just to time; you can use it to represent any other resources used by an algorithm. For example, it is often useful to be able to model memory consumption (see Exercise 35).

page 222:

• If you’re not sure how long your code will take, or how much memory it will use, try running it, varying the input record count or whatever is likely to impact the runtime. Then plot the results. You should soon get a good idea of the shape of the curve.

• Tip 46: Test Your Estimates

page 226:

• Tip 47: Refactor Early, Refactor Often

• At its heart, refactoring is redesign. Anything that you or others on your team designed can be redesigned in light of new facts, deeper understandings, changing requirements, and so on.

page 228:

• Take short, deliberate steps: move a field from one class to another, fuse two similar methods into a superclass. Refactoring often involves making many localized changes that result in a larger-scale change. If you keep your steps small, and test after each step, you will avoid prolonged debugging.

• Tests help with refactoring.

page 233:

• Tip 48: Design to Test

page 237:

• For larger, more complex server code, a nifty technique for providing a view into its operation is to include a built-in Web server. Anyone can point a Web browser to the application’s HTTP port (which is usually on a nonstandard number, such as 8080) and see internal status, log entries, and possibly even some sort of a debug control panel.

page 238:

• Tip 49: Test Your Software, or Your Users Will

page 240:

• Tip 50: Don’t Use Wizard Code You Don’t Understand

· Chapter 7 - Before the Project

page 243:

• Perfection is achieved, not when there is nothing left to add, but when there is nothing left to take away…. -Antoine de St. Exupery, Wind, Sand, and Stars, 1939

page 244:

• “Only an employee’s supervisors and the personnel department may view that employee’s records.” is a vague specification. It could be hard-coded, but should be reinterpreted as an example of a broader specification: “An employee record may be viewed only by a nominated group of people.” The latter will likely lead to an access control mechanism that will be easier to maintain/update.

• It’s important to discover the underlying reason why users do a particular thing, rather than just the way they currently do it.

• Tip 52: Work with a User to Think Like a User

page 250:

• Tip 53: Abstractions Live Longer than Details

page 251:

• As soon as you start discussing requirements, users and domain experts will use certain terms that have specific meaning to them. They may differentiate between a “client” and a “customer,”

• Tip 54: Use a Project Glossary

page 256:

• So how can you tell when you’re simply procrastinating, rather than responsibly waiting for all the pieces to fall into place?

• A technique that has worked for us in these circumstances is to start prototyping. Choose an area that you feel will be difficult and begin producing some kind of proof of concept. One of two things will typically happen. Shortly after starting, you may feel that you’re wasting your time. This boredom is probably a good indication that your initial reluctance was just a desire to put off the commitment to start. Give up on the prototype, and hack into the real development.

• On the other hand, as the prototype progresses you may have one of those moments of revelation when you suddenly realize that some basic premise was wrong. Not only that, but you’ll see clearly how you can put it right. You’ll feel comfortable abandoning the prototype and launching into the project proper.

page 261:

• Tip 58: Don’t Be a Slave to Formal Methods

· Chapter 8 - Pragmatic Projects

page 267:

• When the project’s too big for one librarian (or when no one wants to play the role), appoint people as focal points for various functional aspects of the work. If people want to talk over date handling, they should know to talk with Mary. If there’s a database schema issue, see Fred.

page 268:

• Organize teams much like modules.

page 269:

• This approach can also lead to a more committed set of developers. Each team knows that they alone are responsible for a particular function, so they feel more ownership of their output.

• The project needs at least two “heads”—one technical, the other administrative.

page 270:

• Know when to stop adding paint.

page 272:

• Tip 61: Don’t Use Manual Procedures

• A shell script or batch file will execute the same instructions, in the same order, time after time. It can be put under source control, so you can examine changes to the procedure over time as well (“but it used to work…”).

page 275:

• Web content should be generated automatically from information in the repository and published without human intervention. This is really another application of the DRY principle: information exists in one form as checked-in code and documents. The view from the Web browser is simply that—just a view. You shouldn’t have to maintain that view by hand.

page 278:

• Tip 62: Test Early. Test Often. Test Automatically.

page 285:

• Write tests checking failing conditions.

page 286:

• Tip 65: Test State Coverage, Not Code Coverage

page 290:

• In general, comments should discuss why something is done,

• Commenting source code gives you the perfect opportunity to document those elusive bits of a project that can’t be documented anywhere else: engineering trade-offs, why decisions were made, what other alternatives were discarded, and so on.

page 299:

• Some things you can add relatively easily that look good to the average user include:
• Balloon or ToolTip help
• Keyboard shortcuts
• A quick reference guide as a supplement to the user’s manual
• Colorization
• Log file analyzers
• Automated installation
• Tools for checking the integrity of the system
• The ability to run multiple versions of the system for training
• A splash screen customized for their organization

· Appendix A: Resource

• Design Patterns. A design pattern describes a way to solve a particular class of problems at a higher level than a programming language idiom. This now-classic book by the Gang of Four describes 23 basic design patterns, including Proxy, Visitor, and Singleton.

• Eric S. Raymond’s Papers at www.tuxedo.org/~esr

• Eric’s papers on The Cathedral and the Bazaar and Homesteading the Noo-sphere describing the psychosocietal basis for and implications of the Open Source movement.