DZone
Web Dev Zone
Thanks for visiting DZone today,
Edit Profile
  • Manage Email Subscriptions
  • How to Post to DZone
  • Article Submission Guidelines
Sign Out View Profile
  • Post an Article
  • Manage My Drafts
Over 2 million developers have joined DZone.
Log In / Join
  • Refcardz
  • Trend Reports
  • Webinars
  • Zones
  • |
    • Agile
    • AI
    • Big Data
    • Cloud
    • Database
    • DevOps
    • Integration
    • IoT
    • Java
    • Microservices
    • Open Source
    • Performance
    • Security
    • Web Dev
DZone > Web Dev Zone > How to Read a Program: The Signature Survey, with PHP Examples

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

John Esposito user avatar by
John Esposito
·
Nov. 10, 11 · Web Dev Zone · Interview
Like (0)
Save
Tweet
3.96K Views

Join the DZone community and get the full member experience.

Join For Free

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.

 

Database PHP

Opinions expressed by DZone contributors are their own.

Popular on DZone

  • Are All Kubernetes Ingresses the Same?
  • Caching Across Layers in Software Architecture
  • How to Build a Simple CLI With Oclif
  • Writing Beautiful, Optimized, and Better .NET Code With NDepend Static Analysis

Comments

Web Dev Partner Resources

X

ABOUT US

  • About DZone
  • Send feedback
  • Careers
  • Sitemap

ADVERTISE

  • Advertise with DZone

CONTRIBUTE ON DZONE

  • Article Submission Guidelines
  • MVB Program
  • Become a Contributor
  • Visit the Writers' Zone

LEGAL

  • Terms of Service
  • Privacy Policy

CONTACT US

  • 600 Park Offices Drive
  • Suite 300
  • Durham, NC 27709
  • support@dzone.com
  • +1 (919) 678-0300

Let's be friends:

DZone.com is powered by 

AnswerHub logo