I actually finished the grant about a week ago, but I’ve been so busy I forgot to say anything here!

The last recipe I wrote was a new Basics recipe on subclassing non-Moose classes. The original plan called for a recipe on hooking into Moose’s immutabilization system, but that part of Moose is really nasty, and Yuval Kogman has plans for a major re{factor,write}. There’s really no point is documenting what’s there now. If you’re really intrepid, you can cargo-cult from some other MooseX module.

Thanks to TPF for funding this grant. I think it’s led to some good improvements in the Moose docs. The feedback I’ve gotten on the Manual has been quite positive so far. Of course, nothing’s really ever done, so patches and suggestions are welcome.

Working on the Moose and Class::MOP API documentation recently has once again reinforced the importance of writing documentation. Writing docs hugely improves your APIs. Conversely, not writing docs makes it much easier to write really bad APIs.

I’m hoping that going forward, all new Moose and Class::MOP work will require API docs for all public APIs. This will help us catch bad designs before they’re released.

Here’s some code smells I think docs help catch …

The Parameter of Many Names

For example, “package_name” and “class_name”. Which one takes precedence if both are passed? Or is that an error? Bite the bullet and deprecate a name right now. Add a big fat warning if the deprecated name is used.

Parameter Co-dependency

This shows up as complicated inter-parameter dependencies or exclusions. Your API allows various mutually exclusive sets of parameters, or some parameters always exclude others. For example, you can pass A and B, or B, C, and D, or, C, E, and F. But if you mix sets you get an error. The fix for this is usually to split the one method into several, one per valid set of parameters.

Who the Hell Are You?

Inconsistent naming is painful. Moose and Class::MOP have some real problems with this, for example we use “class” and “metaclass” to refer to the same thing (a metaclass object).

What the Hell Are You?

Inconsistent concepts are also really painful. Another problem for Moose and CMOP. This problem manifests when similar APIs take slightly different sets of parameters. For example, sometimes we take a class name, and sometimes we take a metaclass object, and sometimes we even take both! Considering that with CMOP, we can convert from a metaclass object to a name and vice versa, we need to just pick one thing we want and stick with it.

State of Madness

This is a whole subcategory of smells. They manifest in documentation with phrases like “you need to call methods X and Y before calling Z” or “if you have already called X, then Y returns a foo, otherwise it returns a bar”.

When your docs have this sort of information, you are pushing way too much information about internal object state into the minds of your API users. Hide this stuff. This often can be done by making some methods private and simply calling them as needed when the (fewer) public methods are called.

If a method has multiple return values depending on internal state, you probably need multiple methods, each of which returns the appropriate piece of information.

If you have a lot of methods that will die absent some piece of state, then you may be best served by adding some required parameters to the constructor, and/or some good defaults. A good API has a constructor that returns a fully usable object. Bad APIs have a constructor that gives you an object that requires you to call five more methods before it’s useful.

Fortunately, this isn’t too much of a problem for Moose and CMOP. For the most part, internal state is not exposed in a way that leads to weird complications. The biggest exception was Class::MOP::Immutable, which I refactored before documenting for exactly this reason.


Write docs before you release an API. If you find the docs hard to write, revisit your APIs until the docs flow naturally. If you don’t you’ll pay for it later, when you do write docs and realize you now need to go through some painful and annoying deprecation cycles.

I’m just inches away from declaring the grant done.

Last week, I released new versions of Class::MOP and Moose which feature (mostly) complete API docs. I say mostly because some things are intentionally being left undocumented for now. These are methods with public names (no leading underscore) that I think should be made private, or in a few cases entire classes with really weird APIs that need some rethinking. I think the API docs are done enough to satisfy the grant requirements.

Some of this rethinking has already happened, and doing this doc work let to some refactoring and deprecations, with hopefully more to come.

In the area of Moose Cookbook recipes, I’m one recipe away from done-ness. New recipes cover custom meta-instance and meta-method classes. Back in mid-February I released recipes for using BUILD and BUILDARGS, and applying roles to an object instance.

I expect to have the last recipe finished sometime by mid-April.

I’ve felt for a while like my current position isn’t a good fit for me. Basically, the way they do development is kind of 1995-centric, and I don’t have any power to change it. I find this very draining.

Talking to a friend, he also pointed out that my current job is very isolating. I work from home, and my projects are basically all solo. When I worked at Socialtext, everyone was remote, and so everyone chatted on IRC. Because everyone was in the same isolated situation, we all worked to be less isolated. But with my current position, most folks work at the office, so there’s no IRC. There’s also no planning of work within a group, so even less reason to talk online.

However, the latest humiliation is this. I am a 1099 contractor for my ultimate employer. When I started, I was told I had to bill through a random contracting company, call it TechPeople. This meant using the horrible TechPeople webapp to enter hours, printing a timesheet, signing it, faxing it to my real boss, who would sign it and fax it to TechPeople.

Then my employer merged with another company. The decision was made that contractors would go through the other company’s preferred agency, call it StaffSource. So I start submitting hours through the StaffSource webapp. This webapp is even more horrible than the TechPeople webapp, but on the flip side the approval and submission process is all online. So it involves lots more clicking, but no faxing.

However, because of contracts with TechPeople, I cannot be paid directly by StaffSource. Instead, my ultimate employer pays StaffSource, who pay TechPeople, who pay me. Now TechPeople comes to me and says that they need me to enter hours in their system too. Not only that, but to demonstrate that said hours are approved, I’m supposed to go into the StaffSource webapp after a timesheet is approved there, take a screenshot, and email it to StaffSource.

Apparently StaffSouce and/or TechPeople are too incompetent to make their systems talk to each other, or even just give each other access to their systems. After all, it’s their contracts and terrible apps that make this silliness necessary, so why should I be doing all the work.

So … looking for a programmer? I’m open to contract or FT work, but I don’t want to move. I’d love a position where I worked with other people on projects, rather than solo, but I’m open to solo work, especially for contracts.

My resume is online and I can be reached via email.

Edit: As genehack noted below, since I don’t want to move, it might be useful to know where I live, which is Minneapolis, MN.

In the past, I’ve had telecommuting jobs which involved visiting an office in another state on a regular basis. I’d certainly be open to doing that again (say 2-3 days every 2 months).

I was listening to Massive Attack’s Mezzanine today and I happened to notice that I was missing a track in Rhythmbox. I bought this CD ages ago, and it’s been in my MP3 library for a long time, so it’s funny that I just noticed this.

I went back to my old home-made MP3 server thingy and looked for the track, but it was missing there too.

Now, I could’ve gone downstairs and looked at my dusty shelves of CDs, found the CD (eventually), and ripped it. But that just seems like a waste of time. Instead, I went to The Pirate Bay and found a copy ripped at 320kpbs. It should be on my computer in about 15 minutes or so.

It’s simply more convenient for me to download a “pirate” version than to rip my own CD. I wonder if this is illegal or not, since I do own the media, and when I made the original MP3, I was doing something legal. If someone else makes the MP3 for me and I download it, is that also legal?

♪ I’m a dinosaur, somebody is digging my bones ♪ – King Crimson

I just read a great article/talk by Charles Petzold that was recently (re-)posted on reddit. He talks about how Windows IDEs have involved, and how they influence the way one programs.

Reading it, I was struck by just how ancient the way I program is. I use Emacs, a distinctly non-visual editor. When I work on GUIs, I do it using HTML and CSS, which means I edit the GUI not using a GUI, but through a text interface. Then I have a separate application (my browser) in which I view the GUI.

My GUI development process involves tweaking the GUI definition (HTML & CSS), then reloading in the browser, and back and forth. All the actual GUI behavior is separate yet again, divided between client-side code (Javascript) and server-side (a Catalyst app, these days).

This is truly an archaic way to program. Not only is my editor archaic, the very thing I’m developing is a thin client talking to a fat server. Of course, with Javascript, I can make my client a bit fatter, but this is still very much like a terminal talking to a mainframe.

But I like programming this way well enough, and it seems to produce reasonable results. There are plenty of good reasons for deploying and using thin clients, and Emacs is an immensely powerful tool. HTML and CSS suck big time, but my limited experience with “real” GUI programming suggests that’s just as painful, if not more so.

But still, I feel like I’m old and grizzled before my time. Surely I should be using a powerful new-fangled editor with powerful new-fangled libraries. Bah, kids today and their GUIs!

Occasionally, someone will pop up and say that Moose really needs a book. “X looks good, but it needs a book before I can learn it” is a common meme among programmers.

This is crazy, of course. Demanding a book before you learn something means you’ll never learn a lot of things. Book publishing is a risky proposition for many topics, and with the surfeit of good documentation on the net, it’s getting harder and harder to justify a book for any given topic. Even for books that aren’t failures, writing a book is not a good way for an author to make money.

I put a ridiculous amount of time into the Mason book, and my estimate is that I made $20 per hour (maybe less). Of course, having a book looks great on my resume, but the direct payoff is low. At this point in my career, it’d be hard to justify the effort required to produce another niche book, even assuming there was a publisher.

But the real point of this entry is to highlight just how much free documentation Moose has. A commenter on a previous post mentioned that he or she had created PDF output of the entire Moose manual. There are two versions at the link with different formatting, the shorter of which is about 58 pages. This is just the manual, not the cookbook. I imagine if the cookbook got the same treatment, we’d easily have 100+ pages of documentation. That doesn’t include the API docs, this is all stuff that might go in a book (concepts, recommendation, examples, recipes).

So please stop asking for a Moose book, and just read the one that already exists!

The latest release of Moose, 0.69, marks another completed deliverable in the Moose docs grant. For this release, I finished revising every cookbook recipe in the distro.

My goals were to generally improve the text (Stevan is wordy in hist first drafts ;), and also to make sure we are consistent in our terminology and style.

I also ended moving a fair bit of documentation from cookbook recipes over to the manual. Before the manual existed, some “general doc” pieces ended up in the cookbook for lack of a better home.

In particular, I ended up adding a fair bit of content to the Best Practices manual based on some writing that used to live in Moose::Cookbook::Style.

I’ve just recently noticed people conflating Test-Driven Development (TDD) with unit testing. Why? I’m guessing this happens because folks with the TDD bug evangelise their particular approach to testing, and they’re the loudest. See this silly blog post and the comments (particularly Giles Bowkett). Also see this blog post by Michael Feathers.

I first noticed this conflation in an IRC conversation where someone asked how to pitch unit testing to colleagues. He seemed to think this meant pitching TDD as well. The colleagues were balking as much at TDD as at unit testing, and I suggested separating the two in the pitch.

I caught the testing bug many years ago, and I try to make sure that all the new work I do is well-tested. I introduced unit testing at my previous two jobs, and it helped improve our software quite a bit. I’ve never really done TDD, and I don’t plan to any time soon.

When I’m starting new code, I like to noodle around and explore. Sometimes I sketch out APIs for the whole system, sometimes I just pick a particular chunk and go for it. Once I’ve have something solid, I start writing unit tests. This tends to go back and forth over the course of a project. I write a new class, write some tests, write some classes, write some tests, improve an existing class, write some tests.

Invariably, the tests are written to test the code I’ve just written. The only time I follow TDD is for bugs. When someone reports a bug I write a failing test first, then fix the bug. This is a good discipline, since it ensures that I understand the bug, and that I’m actually fixing it when I make a change.

I don’t have any problem with TDD if that’s your thing. The important thing as that at the end of the day you have good tests with high coverage. You also need a test for every new bug. As long as those things happen, the order is irrelevant.

I think the conflation of unit testing and TDD is unfortunate. If you’re like me, a noodler, you may reject TDD out of hand because your brain doesn’t work that way. But if that causes you to also reject unit testing, it’s a big loss.

I was at Frozen Perl this last weekend, and listening to some of the speakers inspired me to write about giving a good tech talk. I also speak at a lot of conferences, and these are tips I (try to) follow for my own talks. If you’ve seen me speak and think I did a good job, then these tips may be valuable to you. If you think I did a bad job, you can stop reading now.

I’m writing about a specific type of talk here. Most tech talks fall into the category of “here’s a thing you should know about”. That thing might be a project or tool (Moose, Perl 6, Catalyst), or maybe a technique or concept (how to reduce memory usage, unit testing). Typically these talks run between 20 and 50 minutes. If you are doing a tutorial, this advice is not for you, because a tutorial is a different beast.

My number one piece of advice is to give an overview! Speakers often fall into the trap of telling people way too much. Short talks (as opposed to classes or tutorials) are a really shitty way to teach something, but they’re a great way to introduce something. Your goal is to provide attendees with information that lets them decide whether they want to learn more.

A few more pieces of unsolicited advice:

  • Introduce the project or concept. “Unit testing is about writing automated tests for each piece of your system, in isolation.” It’s funny how some folks forget that their audience may know nothing about the topic.
  • As a corrolary, make sure you define (potentially) new concepts clearly – “By automated, I mean the tests themselves are programs, and can be run with a single command. You could run them from cron and report any failures via email.”
  • Tell people what problems this thing solves. “Unit testing makes it easier to refactor existing code with confidence.”
  • Also tell them what problems it doesn’t solve. “Unit testing alone will not ensure that your code meets user requirements.”
  • Show some some details, and allude to the rest. “Here is an example of Test::More from CPAN. You can see the use of the ok() and is() functions. (explain those two). There are many more functions in Test::More, and many more useful test modules on CPAN such as Test::Exception and Test::Output.”
  • Do not go into detail on every little option and feature. This seems to be an easy trap to fall into. Don’t do it. It’s incredibly boring, and you’ll never finish explaining everything in the time you have available.
  • Time yourself! So many speakers get through half their slides, or get through all of them in half their time and then look dumbfounded. You don’t need a stopwatch, just look at the clock. If you’ve presented a couple times, you may notice that you tend to have an average time per slide. I’ve noticed that my own time is approximately 1 minute per slide.

Have your own advice? Write a comment or your own blog entry.