names

How to point in code

In my previous post, I explored why deixis is helpful, how it shows up in our language, and how its use in source code is hampered by limitations in our current programming ecosystems.

I promised I’d explain how we could remedy this problem to increase the expressiveness of our code… That’s what this post is all about.

It starts with names

The magic that makes the web “hyper” is not really in tags. Sure, we use ... to point at something–but there are other ways to point. As I said in my previous post, line numbers point. Method names in source code point at their decl or their impl. Statements like using namespace std point. Names of build-time dependencies in maven pom.xml files point.

The real magic is that the web has so many things to point to. It has names (notice where “name” appears in the previous paragraph). Every resource–even ones that are dynamically generated–has a URL. Individual paragraphs or tables or images inside a resource can have names, which lets us point to them, too.

We value names.

image credit: xkcd.com

So, if names are so valuable, part of how we make code more “hyper” is to increase the availability of names. Here are some ways to do that.

Continue reading →

On bread recipes, maps, and intentions

[I’ve been quiet for the past three weeks–not because I have less that I want to talk about, but because I have more. Major wheels turning in my head. I’m having a hard time getting from the “intuited ideas” mode to the “crisp enough to put it in writing” mode, though. Consider this a down payment on some future discussions…]

One of my mother’s talents is bread-making. She’s been kneading and baking and pulling beautiful loaves out of the oven for as long as I can remember. Bread is one of the ways she says “I love you” to family and friends.

photo credit: treehouse1977 (Flickr)

A few years back, she created a cookbook full of family recipes, and gave one to each adult child for Christmas. I was struck by how she began the bread section. Instead of launching right into the recipes, she included a couple of pages of “bread theory”, if you will. The section about water is typical:

“Water — Just about any edible liquid could be used as the base for bread. Some that come to mind are vegetable cooking water, potato water, milk, and so on. There is no problem with substituting any of these for liquid called for in a recipe, but you should keep in mind that if the liquid is salty, the salt should be adjusted; if the liquid is sweet, the sugar should be adjusted… Fresh milk can be a problem because of enzymes that would prevent yeast action. For this reason, most old recipes that call for milk specify that the milk be scalded first. This isn’t necessary if you are using water and powdered milk, but remember that the mechanics of the recipe probably depend on at least warm milk (so use warm or even hot water).”

If you’re wondering why I am writing about bread recipes in this blog that focuses on software craftsmanship, consider how much that paragraph resembles a really high-value comment in source code.

It has to do with principles and intentions.

Software is all about recipes, right?

Recipes are a lot like software algorithms (especially in imperative programming styles): First, do this; next, do that; wait 25 minutes; return new Loaf()… We even talk about “recipes” and “cookbooks” when we make catalogs of software techniques.

How is this metaphor instructive… or worrisome?

Continue reading →