Monday, November 17, 2008

Generative Ambient Music: Bloom

One of the techniques I describe in The Productive Programmer is focus, distancing yourself from the all too common distractions in modern office environments. I suggest that you can wear headphones (or earbuds) while coding as an indicator that others shouldn't bother you. Some developers can code to music (in fact, some developers have a hard time not coding to music), but others fine it distracting. If you are in either group, you should try ambient music. The goal of ambient music is to create non-offensive background music. I find Muzak-style background music incredibly annoying and distracting, partially because they always choose sappy music (or taking good music and sappifying it) and partially because of a personality quirk described here. Ambient music strives to create a sonic background that not only doesn't distract but qualifies as good music. You can search for ambient music as a category on Amazon. Ambient music frequently uses techniques borrowed from Minimalist music, where you create a melody (which is too stong a term for some minimalist music) that repeats with minor variations.

Brian Eno is one of the pioneers of ambient music. He and Robert Fripp recorded the track The Heavenly Music Corporation on the album No Pussyfooting in 1972 by combining some experimental tape loop techniques from Eno, combined with Fripps guitar loops (called Frippertronics). No Pussyfooting is still available, and quite enjoyable. But the interesting part about it for this post concerns how it was created. Once Eno and Fripp had all the equipment set up, they started the tape loops and recorders for the background track and retired to Eno's front room and drank tea while the album recorded itself. No Pussyfooting has some early examples of generated ambient music (they were certainly not the first to experiment with generated music, but the first in a main-stream context). Eno and Fripp created several albums together. Eno has created a large catalog of ambient music (including the classic Music for Airports, recorded by several ensembles including the incredible Bang on a Can All-stars), and Fripp expanded the ideas behind Frippertronics using electronics for a stunning collections of recordings called Soundscapes.

Which brings me finally to Bloom. Bloom is an iPhone application created by Brian Eno and Peter Chilvers. When you launch Bloom, it starts a gentle drone sound as a background, and gives you the option to create ambient music by tapping the screen. When you tap, a note plays based on the location of your tap. You can tap single notes or chords. After about 5 seconds, the note repeats and continues while it gently decays. Using Bloom, you can create your own ambient music. I can play with Bloom for hours. It is one of the best iPhone applications I've found: a trully innovative application that takes great advantage of the iPhone interface.

The other option when you start Bloom is for it to generate music for you randomly. That brings us back around to focus. Using Bloom, you can generate unique, non-distracting music for an entire day. Rather than buy a collection of ambient recordings, you can generate your own ambient music. Bloom lets you set several "moods", changing the tonal range and drone sounds to add just enough variety in the music to keep it just interesting enough to not distract. What used to take tons of studio equipment now runs on the iPhone. This makes a great way to help enhance your focus in noisy environments. Allow Bloom to create music for you that doesn't distract yet effectively drowns out all the other distracting sounds in your cube-ridden environment. Bloom is a great example that the iPhone isn't just another mobile device: it's a new platform for software development.

Friday, November 07, 2008

Comments == Code Smell

I am sometimes asked about my position on code comments, and, like most things, I have strong opinions about it. Two kinds of comments exist:

  • JavaDoc-style comments (which encompasses JavaDoc, XMLDoc, RDoc, etc), which are designed to produce developer documentation at a high level (class and method names and what they do)

  • In-line comments, generally scattered around the code to indicate a note from developer to developer

Both kinds of comments represent different smells, each with different odors depending on the target.

What makes comments so smelly in general? In some ways, they represent a violation of the DRY (Don't Repeat Yourself) principle, espoused by the Pragmatic Programmers. You've written the code, now you have to write about the code. In a perfect world, you'd never hove to write comments for this purpose: the code will be expressive enough that someone who reads it will understand it. Two things help achieve this result: expressive, readable languages and the composed method pattern.

The language makes a big difference as to the readability of the code. If you write in assembly language, you're pretty much forced to write comments; no one on earth can read the code directly. As languages have matured, you can get much closer to the ideal of self-documenting code (which was explicitly attempted in Literate Programming). Especially in the modern wave of non-ceremonious languages (like Ruby, Groovy, Scala, etc), you can craft extremely readable code. To this end, ThoughtWorks projects generally avoid the more magical features of languages (like the implicit global variables in Ruby, for example) because it hurts readability. One of the side effects of dynamic typing is outstanding method names. The method name is the only vector of information about what the method does (you can't crutch on return or parameter types), so methods tend to be named much better on the dynamic language projects upon which I've worked.

The second key to readable code is not to have too much of it, especially at the method level. In Smalltalk Best Practice Patterns, Kent Beck defines composed method (which I write about extensively in The Productive Programmer). Composed method encapsulates the idea that all your methods should do one and only one thing, making them as small as possible. The side effect of this discipline leads to public methods that mainly consist of calls to a large number of very small private methods, each of which do only one thing. Composed method has lots of beneficial side effects on your code: small methods are easier to test, you end up with really low cyclomatic complexity for your methods, you discover and harvest reusable code chunks more easily, and your code is readable. This last one brings us back to the topic of comments. If you use composed method, you'll find much less need to have comments to delineate sections of code within methods (actual method calls do that), and you'll find that you use better method names.

Now let's talk about how this applies to the two types of comments. First, where are comments indeed useful (and less smelly)? If you are writing an API, you need some level of generated documentation so that people can use your API. JavaDoc style comments do this job well because they are generated from code and have a fighting chance of staying in sync with the actual code. However, tests make much better documentation than comments. Comments always lie (maybe not now, but on a long enough timeline, all comments will become outdated). Tests can't lie or they fail. When I'm looking at work in progress on projects, I always go to the tests first. The comments may or may not be there, but the tests define what's now done and working.

We were on a project where the client insisted on Javadoc comments for every public class and method. We started the project adding those comments, but eventually stopped. When doing agile development, you don't want anything that hampers refactoring. Having comments in place caused a dilemma: do I refactor the method and change the comment (the most work), refactor the method and leave the old comment (with the theory being that I'll change it again later, and would rather just have to update the comment once), or not refactor? No good options here. Having pervasive comments discourages refactoring because it adds significant extra friction. On this project, we abandoned commenting as we went along. The last week of the project we literally did nothing but go back and add comments to the code, which worked well because the code base had settled down by that point. But notice what's lurking in wait: the client wanted all the comments there to make it easier to maintain in the future. But who's to say that whoever maintains that code will keep the comments up to date? You have the same DRY violation as before. If they maintain the tests, they have to change as code changes because they are executable.

The new wave of Behavior Driven Development tools (like JBehave, RSpec, and easyb make this "executable specification" style of comment + test feasible. I expect to see the usage of these tools skyrocket because they give you documentation that has a fighting chance of staying up to date.

Inline comments are almost always a smell. The only legitimate use of inline comments is when you have some very complex algorithm that you need to have some thoughts about beside the code. Otherwise, the presence of inline comments indicates that you've written code that needs explanation, meaning that it cries out for refactoring. I frequently troll code bases upon which I'm working to look for inline comments so that I can refactor the code to eliminate the need for them.

Comments are a great example of something that seems like a Good Thing, but turn out to cause more harm than good. Fortunately, we've figured out how to achieve the same benefits that comments allegedly provide with tests, particularly BDD-style tests

Monday, November 03, 2008

Voices That Matter: Crafting Software Conference

Voices that Matter conference logo Just a quick note to let my readers know that I'm speaking at the Voices That Matter: Crafting Software Conference coming up in San Francisco in early December. I'll be speaking on Real-world Refactoring, and I'll be doing a pre-conference tutorial called 10 Ways to Improve Your Code. This is based on material from The Productive Programmer and my 90 minute conference talk of the same name, but I'm expanding it to 3 hours. That shouldn't be hard because there's a lot of rich material there, and 90 minutes always made it hard for cramming in that much information Now, each topic can spread its wings more.

Of course, I don't mention every conference for which I'm speaking in my blog (otherwise, it'll be nothing but conference announcements). I bring this one up because you can get a discount: use CSNPKRA as the priority code when you register and, lo and behold, a discount! Don't ever say you never got anything of value from this blog!