Tool marks are a term for details in an object that indicate how it was made. I learned the term in the context of woodworking, where it's a common way to learn how an object was made or even establish a date for an antique. (Just so there's no mistake: I'm no woodworker, I just watch videos from a few!)
For example, pencil marks used to lay out a dovetail may remain on a finished product, especially in a "hidden" area such as the back or underside. Some marks are a consequence of the tools used: circular saws were only invented in the 19th century, and leave a distinctive circular impression when used to cut wood.
Woodworkers consider some tool marks to be evidence of craftsmanship, distinguishing their work from big-box CNC-manufactured objects.
Tool marks are also a common way of learning how a piece was built. This is useful for learning purposes, but also critical when repairing or modifying an object.
Woodworking is a kind of engineering, maybe with a heavier emphasis on craft over rigor than, say, aeronautical engineering. So, how does the idea of "tool marks" carry over into software engineering?
History
The first option that comes to mind is a kind of accidental tool mark: as it is modified, code often carries evidence of its history. Maybe a class has some unused methods that were once used (and are hopefully covered by unit tests!). Or maybe a function has some extra synchronization in place that isn't needed anymore.
In general, one goal of refactoring is to erase such marks -- much like a few strokes with a smoothing plane might remove the telltale patterns of a bow-saw. When might it be useful to leave such marks in place?
Conway's Law
Conway's law states that a system takes the shape of the organization that created it. In a company developing software, this might show up in the high-level architecture of an application, where independent teams own individual components. It may even manifest as different coding styles in those components. I've worked on web applications where the frontend team put in a great deal of effort to work around bugs in the backend, for example.
In open source development, the organization usually looks like a large number of contributors with a limited understanding of the software as a whole. The resulting software often has a "bolted-on" feeling, where each contribution adds a new class or file while making minimal changes to existing code, in hopes of not breaking anything.
Many open-source projects embrace this, providing well-designed interfaces for contributed components, whether within the codebase or as separate plugins. For example Bugwarrior integrates with lots of services, and no one person understands all of those services in detail. A counter-example is the Linux kernel, where a herculean effort at code-review ensures that all in-tree code is of good quality and maintainable by others.
Design Patterns for Learning and Understanding
Some of the best code I've seen contains intentional tool marks. Here, design patterns are used as a common language across applications, and the problem domain is transformed into the "shape" of a well-known design pattern or algorithm.
For example, a complex problem may involve a search operation. If that search operation is structured as a depth-first search, with names and comments chosen accordingly, then a reader can recognize it immediately and understand the solution more quickly.
I recently invented some clever names for classes while writing new code, and a reviewer suggested that names like "Factory" and "Builder" would be better, as their functionality matched those patterns. Using such names helps readers to quickly understand what they're looking at without first reading and reasoning about the implementation.
This approach not only helps experienced readers understand code they are reading, but also helps less-experienced engineers to understand design patterns. A pattern such as "decorator" can be a bit esoteric to learn about in a vacuum.
But after seeing two or three well-described implementations of this pattern in code, it starts to feel familiar and simple.
Other Marks?
What other "tool marks" can you think of in software?
Top comments (0)