Show me the Code

I’m lazy when it comes to code. Not in a bad way, but in an efficient way. I want to get to the crux of the matter quickly and move on. Truth be told, that’s why I like TDD—I don’t have to remember anything more than I need to know right now. My tests remember everything else I knew, but I digress.

When I start evaluating a new library to see if its something I want to use, code is what I want to see. Sure, tell me what it does, briefly, then move into the basic use-case. As an example, consider the front page of Ruby-Lang.org.

You’ve got access to all the information you need, but right up front and center (almost literally) is some code showing you how to use Ruby.

If you’re starting a new library, make sure to put the code right up front. I know there are any number of projects I have on GitHub that fail this test, but I’m not out purchasing domain names and designing custom sites for my projects either. If you bill your project as “easy” and “powerful”, show me, don’t tell me.

Otherwise, you’re no better than the phone commercials][] that promise the world will bow before me if only I use their phone, without, you know, showing their phone being used.