I write lots of code. But I want to be better and faster at reading code. When I had the privilege of working with @ranguard I discovered he is a code reading cheetah and I always envied that. So I’ve decided to practice by reading the source code of various CPAN modules. I’m starting with Plack.

Plack

Plack describes itself as a set of tools for using PSGI (the Perl Server Gateway Interface).

The earliest release of Plack on CPAN is version 0.9000 from 2009-10-13. There were releases several times a week for the first two years. Impressively, in 2012 releases were still happening roughly once a week. In 2013 things seem to have cooled and now releases happen about once a month.

The code itself is written tersely and with attention to detail. There are almost no comments. In fact 43 out of 71 files have fewer than 3 comments. Of course the code is very well written which makes comments less necessary and nowadays there is quite a bit of excellent POD as well.

The code also makes heavy use of callbacks (code references). That is to say its heavily event driven. Which makes sense given the event driven nature of web servers. For me this gave the code a JavaScript flavor. Take for example Plack::Util::foreach which works just like jQuery.each() by iterating over an array calling a code reference on each item.

Plack::Util::foreach([1,2,3], sub { print shift }); # prints "123"

Background reading

The most important thing to read is the PSGI spec. This is the problem Plack was built to solve. Its clear and well written but perhaps also a little boring and lacking in context. Still I found it very helpful to refer back to while reading the code.

Getting started

~/code ⚡ git clone git@github.com:plack/Plack.git ~/code ⚡ cd Plack

The first thing I noticed is a cpanfile containing a list of the project dependencies. Because understanding and running the tests is often useful when reading new code I installed the dependencies using Carton and ran the tests.

~/code/Plack ⚡ carton ~/code/Plack ⚡ prove -rl t

Who works on Plack?

Lets get a feel for who is involved in the project.

~/code/Plack ⚡ git shortlog --summary --numbered | head 1567 Tatsuhiko Miyagawa 70 Kazuho Oku 68 Tokuhiro Matsuno 20 Daisuke Murase 20 Jesse Luehrs 19 yappo 16 Karen Etheridge 16 Mark Stosberg 12 hiratara 11 Stevan Little

How big is it?

~/code/Plack ⚡ tree lib | tail -1 17 directories, 70 files ~/code/Plack ⚡ cloc . 2>/dev/null | tail -13 ------------------------------------------------------------------------------- Language files blank comment code ------------------------------------------------------------------------------- Perl 82 2889 3341 5309 Bourne Shell 8 55 138 251 YAML 1 0 0 19 HTML 3 2 0 14 Python 1 2 1 6 Javascript 1 0 0 1 CSS 1 0 0 1 ------------------------------------------------------------------------------- SUM: 97 2948 3480 5601 -------------------------------------------------------------------------------

What is the lib directory structure like?

Unfortunately with 71 files in the lib directory its hard to grok whats happening in a single glance so maybe thats not a great question. Instead I found it helpful to group the code by functionality. I came up with 3 major categories which look like this:

Category 1 - Modules for loading and running PSGI servers plackup Plack::Handler Plack::Handler::* Plack::Loader Plack::Loader::* Plack::Runner

Category 2 - Modules for building PSGI apps Plack::App::* Plack::Builder Plack::Component Plack::Middleware Plack::Middleware::*

Category 3 - Modules for testing Plack::Test Plack::Test::* Plack::HTTP::Message::PSGI Plack::LWPish



However I also got crazy and went ahead and listed everything in the lib directory along with a brief description. I guess it might be handy for reference purposes. The numbers (1), (2), (3) below correspond to the three categories I listed above.