To Name A Rose

This week’s meeting of the BSC had lots of potential for discussion, debate, and religious crusades — the topic of discussion was naming.

Naming things is an important part of a programmer’s daily life. He creates a new variable, function, module, script, file, or other tool literally every few minutes. And they all need a name.

A programmer’s life is acted out in text. Everything we produce is text. We use text because both the computer and the humans can be made to understand it. But we name things because humans need more information about the program than the computer does. In fact, what a name encodes is meta-information. It is information about the program itself, which is lost at compilation time. One doesn’t need this information to run the code. One only needs this information to edit the code. Thus it is extra information that humans need, because their job is to edit the code, not run it. So naming is very crucial for us, and is more than a trivial study.

There. Now that I’ve had the chance to philosophize about it, what follows is an assorted collection of the things we had to say about naming.

When naming unit tests, omit the word “test.” It’s redundant. It’s a relic from old testing frameworks that is no longer needed. It’s already clear that it’s a test. You can also omit the name of the method you’re testing — it bears no real relevance to the test itself. For example, what if a method name changes from “lessThan” to “worseThan?” The tests are still correct, but they refer to a method that no longer exists. In addition, you’re often testing more than one method at a time. And if you need to trace a method back to its test suite, you should be using your IDE’s call hierarchy anyway (or simply a “find across files” if your IDE isn’t that fancy).

Better to name your tests by what the test itself does, not which parts of the program it’s testing. If you’re testing that

lessThan(-1, 0)

returns a negative number (to indicate the first argument is less than the second), then don’t name it “testLessThanNeg10” — name it “neg1IsLessThan0.” See? Now we understand what fact is being tried. Much better. Some people phrase their test names as “given, when, then” statements, but these words seem redundant, too. We already understand how tests work, so we can omit these words without losing any meaning.

Looking even deeper, we began to wonder why do we name tests in the first place? They are never used in code; they are only run by the unit test framework. So why bother naming it? Well, it turns out the names behave as comments. When a test fails, you can read the name of the test and immediately have some knowledge about the failure. You can’t do that with real comments, because those aren’t normally included in a test report. However, testing frameworks do allow you to attach a message to each of your assertions, so does that make the method name redundant? Perhaps.

Another lesson to learn is that variable naming is almost as important as method naming. Sometimes we tend to focus on the latter a lot more, because we are sometimes more concerned with what something does rather than what something is. Some argue that you should never inline a constant, though I would argue that there is no benefit to making a variable that is only used once.

Variable naming is important, but the goal is not always uniform. Sometimes you might in fact want to name a variable by what it’s used for rather than what it is. For example, in tests, with fake data, the content of the data itself is often unimportant. It helps in these cases to name variables




. This helps the you determine that those particular pieces don’t apply to the actual test. Furthermore, you can shape things so that they look like real data in a UI, but they’re still obviously fake. You might, for instance, name all insurance agents in the database as “James Bond.”

We asked ourselves about package/module names. Do we normally use them for categorization, or for common purpose? Do we lump all the models in one folder and all the views in another? Or do we put all the MVCs for Banks in one place and all the MVCs for Videos in another? This is a debate about organizing programs in an encyclopaedic fashion. Do you index by one set of categories or by another, orthogonal set of categories? Reginald Braithwaite has said some intelligent things on the subject. He might argue that these are two completely valid, but completely contradictory layouts.

Someone pointed out, partly joking but not entirely, that Ruby programmers are sometimes a bit reluctant to name things because their IDEs do not typically support it. The upshot is that different languages and even different toolchains may have an effect on name choices.

Perhaps the most important, introspective question came from a blog post by J.B. Rainsberger. Why do we name things? Some answers:

  • To discover their purpose. (jbrains’ argument)
  • To get a handle on things, to gain control over things. (Western hermetic magic concept, related to jbrains’ argument)
  • To have a common domain language. Now whenever anyone says anything, you immediately know what they’re talking about.

A prime example of a domain language that every programmer already knows is that of design patterns. Back in the 80s, the Gang of Four realized that there existed certain common patterns, and that we needed a common way of referring to them. Much how mathematicians come to agree on a common set of notation, so they can share their findings with each other. Naming gives us the power to discuss complex subjects and still be understood.

Oh, and one more thing. How many of us have developed a new feature, and agreed upon a name, only to have marketing give it a different name when it comes time to release? Ignore whatever marketing tries to call it. This is just the flavor of the month. A dev team should pick one, consistent name, and stick to it. This reduces confusion, even if you do have to use a different name when you talk about it to people outside the dev team.

Recipes For Mediocre Journalism

Now that I've started a blog, I can start criticizing everyone else's blogging techniques. Here are some common blogging anti-patterns that I continue to see time and time again.

"What Industry A Can Learn From Product B"
Ex. What Angry Birds Can Teach Us About Air Traffic Control
Ex. What a Person's Accent Says About Their Daily Bowel Movements

"The 10 Best X"
Ex. 20 Dating Websites That the Author Just Found on Google in the Past 10 Minutes
Ex. The 10 Best Places to Have an Epileptic Fit

Any article about human psychology, ever.
Ex. Seriously, ANY one of them
See Also: How to read health news (you know it's bad when a government institute has to write a tutorial about it)


To be continued...

Learning Me Some Erlang

This week I've begun in earnest to learn some Erlang and start using it in a meaningful way.

At this week's session of the Boston Coding Dojo, we set up and started in on our [top-secret] Erlang project. One of the biggest stumbling blocks we came across was when we wanted to do what was essentially a loop. We resisted the tail call recursion. Instead, we refused to believe we needed recursion. We said to ourselves, "There must be some way to just execute some function X number of times. The standard library must have something for this." We looked all through the lists module with no success. After having read a couple of "getting started" guides on Erlang, I felt that constructing our own recursive method was ultimately the proper solution. Eventually we caved and wrote what I feel is some straightforward and concise code:

%% Generate markers and append them to a URL string.
markers_list() ->
    markers_list(3, "").
markers_list(0, String) ->
markers_list(N, String) ->
    markers_list(N - 1, String ++ "&" ++ marker()).

marker() ->

The code is simple and it works, but it left something to be desired. We kept having this feeling that we had missed something obvious in Erlang's stdlib, that it shouldn't be this cumbersome to just concatenate a few random strings. We told ourselves that in a larger project we would certainly genericize the behavior in some sort of utility method. I had my doubts about this, but it made me curious. If this was the kind of thing which really lent itself to a utility method, then why didn't something like it already exist in the stdlib?

When I got home I started trying to think of other ways to do this that would make use of built-in features. I tried to think in terms of the ways other languages would accomplish the same thing, and tried to think of list comprehensions that could build the same sort of URL. That's when I realized that our marker() method was really just a generator, in the Python sense of the term. And what we wanted was to fold the results from this generator into a single string. And earlier we said we wanted to genericize this to the point where we could replace marker() with any old function. We wanted a Python-like generator. So with this in mind, I threw together the following code:

%% Generate markers and append them to a URL string.
markers_list() ->
    lists:foldl(fun(Marker, URL) -> URL ++ Marker end,
                gen(3, fun marker/0, [])).

%% A Python-like generator. This is a finite generator, however. It generates all
%% results at once and inserts them into a list.
gen(0, _Function, Result) ->
gen(N, Function, Result) ->
    gen(N - 1, Function, Result ++ [Function()]).

marker() ->

What do you think? Is this more readable, or more modular? Which method is better? Is there yet an easier method that doesn't require me to implement my own generator?

Improving Search Results

Improving Search Results With Search Operators
Tricks you can use with Google, Microsoft Live, or pretty much any search engine

You know, I'm a programmer, so I'm plenty used to typing operators and keywords on a command line, using regular expressions and that sort of thing, but I never tried out Google Advanced Search Operators before. You know why? Because they are so darn hard to find on Google's website. I had to click through like 5 different sections of help to find it.

Anyway, I can forgive them for that, because I now have a far superior toolset for finding what I need! First off, for those that do not know, search operators are just keywords or symbols that have special behaviors when entered into a search. Some of you may already know a few, such as the quotation ("") operator that lets you designate a phrase that you would like Google to find in that exact form.

Google's Advanced Search page can do a lot of these operations for you, without you having to memorize the keywords or look them up every time you search. However, it doesn't let you do quite everything that the Google engine is capable of doing.  Let me give you an example of how these operators have helped me out:

A neat feature that shipped with my Mac OS X is a little RSS Screen Saver that Apple threw together, that takes the text from your news feeds and displays them to you in a cool 3-dimensional rotating graphic. A headline swings by you in 3D, and if it piques your interest you press a key and it opens up the article in your default web browser. (Users can also make such a screen saver themselves, using Quartz Composer).

Anyway, I use this screen saver to display the most recent articles about the robotics industry so I can read about them and forward them to my co-workers. The way I accomplished this was not to find some robotics blog and then subscribe to its news feed — rather, I went to Google News and searched for


. See, Google News also makes every single search available as an RSS feed, you can use this neat feature to get feeds about absolutely anything that you want! Just search for what you want news about, and click on the icon that appears on the right side of the URL box in your web browser. So there's another helpful hint for ya.

Looking at my search results for robotics, I realized that wouldn't be enough. I wasn't getting any returns on plain old robots, I was often getting treatises on the field of robotics, or people mentioning robotics in an off-hand fashion. So what I did next was, I used my limited knowledge of search operators to search for

[robot OR robots OR robotics]

to be sure that I covered all the ground I could.

That was satisfactory for a while, but it would always bring up so much cruft. I can't tell you how many articles from local newspapers it turned up about high school robotics competitions and little "robot" toys and the "Transformers" movie and sci-fi TV shows and on and on. More articles on "Wall-E" than I could ever have time to read. I obviously need a way to turn it down. A colleague of mine was having some better luck searching for

[autonomous robots]

— articles that contain the word autonomous tend to be much more serious and, not surprisingly, much more geared to our line of work. I don't know why I never thought of it before, but words like "autonomous" and "unmanned" are used much more often in the military or technology sectors than they are in the sci-fi world. So I wanted to incorporate something like this into my search, and I wanted to do it right this time, so I looked up all the search operators.

The best one I found was the "synonym operator" (tilde ~) which searched for a certain word and all of its synonyms! Perfect! Now my screen saver searches for

[~robotics AND ~autonomous]

. This returns articles that "Have some form or synonym of the word 'robotics' and also some form of the word 'autonomous'". This search is now the equivalent of

[(robot OR robots OR robotic OR robotics) AND (autonomous OR autonomy OR automaton OR automation OR unmanned)]


Now that is a superior way to search.

Go here for the full listing and description of Google search operators. You can find the ones for Microsoft Bing here. Most search engines use the exact same operators as these two. So take a minute to learn them and you won't be sorry.