How to Read a Program: The Signature Survey, with PHP Examples

As Donald Knuth said: Good programmers don't just write for computers; they write for other programmers, too.

More exactly: good programmers write so that other programmers will understand what the program is telling the computer to do.

This precisely does not mean 'write more comments': rather, the code itself is supposed to be intelligible to other humans. (Unless you're writing in machine code, of course, like a weirdo, or a god.)

How do you achieve this?

Well, it isn't easy, but many coders have found Robert Martin's Clean Code tremendously helpful.

But there's a flip side to writing code so that others understand it, and that is: understanding code that others write.

So how do you do that? or rather, is there a method for that?

The code-reading problem is the developer's version of the high schooler's problem: you know how to read individual words and sentences, but how do you get a feel for the entirety of the novel? especially when the novel is War and Peace? (or the Linux kernel?)

For natural-language books, Mortimer Adler offered a solution: take the book in layers, always keeping your eyes on the whole. Read the first paragraph and the last paragraph, absorb the table of contents, read the beginning and end of each chapter, and so forth. Adler's 'How to Read a Book' has been in print for over seventy years; for recall and academic analysis, at least, it works very well.

For code, Ward Cunningham's 'Signature Survey' method isn't too different. Structure is crucial to all code, of course; but, for computer languages, whose lexica are incomparably minute next to the lexica of natural languages, structure is even, perhaps incomparably, more important. Wherefore: the Signature Survey looks at structure alone.

As the creator himself puts it:

In this case [=summary of the Java 1.3 source code distribution] the summary is formed by eliding all but select punctuation characters from the file. I call this the file's "signature". The quantity of punctuation (length of signature) gives an intuitive sense for the size of the file while the patterns that appear in the punctuation adds to this a sense of complexity and repetition. 

Here's a couple of examples:

ComponentPeer ;;;;;;;;{;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;}
ContainerPeer ;;{;;;;} 

The fuller version of the Signature Survey includes more complex visualizations, painting a somewhat finer-grained picture of Java 1.3 -- totally worth reading, and probably worth applying to programs you're picking up, at least before you dive in headfirst.

And that's what Sameer Borate did, to some PHP files from WordPress.

For example, the signature of this (wp-blog-header.php):

<?php
/**
 * Loads the WordPress environment and template.
 *
 * @package WordPress
 */
 
if ( !isset($wp_did_header) ) {
	$wp_did_header = true;
	require_once( dirname(__FILE__) . '/wp-load.php' );
	wp();
	require_once( ABSPATH . WPINC . '/template-loader.php' );
}
?>

is this:

wp-blog-header.php : {;;;;}

Take a minute to get a feel for how this works.

Then read more of Ward's original Signature Survey document, or the rest of Sameer's WordPress signature summaries, plus his shell and PHP scripts to signature-summarize your own code.