Putting It All Together

| 3 Comments

The Perl community gets a lot of things right right now. Consider the CPAN: we expect a few standards of compatibility and kwalitee, but as long as you adhere to rough consensus, your work is useful and usable to a million other Perl programmers.

We have a good understanding of how to package your work and how to mark dependencies and how to document it, and that rough consensus allows sites such as search.cpan.org to provide infrastructure that allows me to read cross-linked documentation of the 84,944 modules on the CPAN (as of this afternoon).

Even the standard documentation mechanism for Perl modules (POD, adhering to a loosely-agreed organizational scheme) contributes to the utility and usability of the Perl ecosystem. You expect perldoc Your::Distro::Name to display something useful for the distro, even if it's a table of contents to other documentation. Larger projects or frameworks have introductions and tutorials and guided recipes (you know, like a "book" for "cooking", except without infringing on a trademark). If you know what you're doing and need a mere syntax refresher—or if your problem is small enough that a handful of lines of code can solve it—the SYNOPSIS section of the documentation is often enough.

Other times it isn't. Explain Plack in a paragraph, or DBIx::Class, or Perl::Critic, or Bread::Board (or explain Bread::Board at all; sometimes I think Stevan and Yuval are the only people who understand it).

Many of the wonderful new tools I want to use in Perl right now have a steep learning curve. I understand that some of them (Devel::Declare) have essential complexity that users must master before using the tool effectively. Not everything does—look at Test::Tutorial, which takes a subject which seemed complex and confusing in 2000 and 2001 and is commonplace and expected in 2010. Writing effective tests well is still an art of experience and good taste, but half an hour with that documentation has been enough to explain the basics to thousands and thousands of people.

I recognize that a SYNOPSIS won't suffice for demonstrating even a simple Catalyst application, with user authentication and logging and route dispatching and a model which is more complex than a Blog with Posts and Comments, but perhaps there's something in between a "Hello, world!" tutorial and the gory documentation of individual components and their methods. (Catalyst does this better than almost every other CPAN project.) Maybe larger projects should consider guided walkthroughs of real and modest-sized applications, especially if they include discussions about design goals and tradeoffs.

We're good at documenting reusable pieces of larger systems—CPAN encourages us to build applications that way. Can we improve further?

3 Comments

Honestly once you catch it, Bread::Board is really simple. It takes all the messy builder logic you need to wire up your classes and moves it outside the object. I recently converted XML::Toolkit to use it and removed something like 600 lines of code, it's a wonderful thing.

Took me for f***ing ever to catch it though, I kept thinking it was more complicated than it was.

Stevan's article in Dr Dobbs was what made me "get" Inversion of Control. Though the article describes Stevan's first attempt at Bread::Board, named IOC, the ideas in it are very relevant and enlightening.

http://www.drdobbs.com/web-development/184416179

Someone ought to refresh this article to talk about Bread::Board. Maybe I will. :)

Modern Perl: The Book

cover image for Modern Perl: the book

The best Perl Programmers read Modern Perl: The Book.

affiliated with ModernPerl.net

Categories

Pages

About this Entry

This page contains a single entry by chromatic published on August 20, 2010 4:37 PM.

On Deployment was the previous entry in this blog.

Mechanism versus Policy is the next entry in this blog.

Find recent content on the main index or look in the archives to find all content.


Sponsored by Blender Recipe Reviews and the Trendshare how to invest guide

Powered by the Perl programming language

what is programming?