Today, I finally read Jeremy Ashkenas's blog post on [Literate Coffeescript]() and really have to say, I agree with the point that he is trying to make.

In essence, we as programmers have become detached from the function that our code is trying to accomplish. To make up for this, we've created huge systems of integration to keeping track of what we are working on.

But really, I've found that even some of these programs don't quite match up with what we are trying to accomplish. Today I found myself trying to talk out the possible routes we could take for a feature and found myself at a loss. The thought would have been overwhelming to put in as a comment or description in Pivotal Tracker, emails just get lost in the mass of back and forth with clients, and our Github repos aren't persistent because of the nature of our company workflow. The best thing I could think to do was build up a gist in markdown and then link to it in the Pivotal comment stream.

But to return to Jeremy's post, the goal of our post should be in front of our eyes when we are programming. Should we have to keep returning to our Pivotal to see the progress of our code?

This gets to the heart of making more readable code. It's part of the reason why I favor very explicit and human readable code. What's more understandable find or findFromIdForCurrentUser.

But, Jeremy's Literate Coffeescript takes things to the next step. It puts describing what a function does first. You don't have to chase down user stories, thoughts, etc.

Now something like Pivotal can be used for what it does really well: keeping track of estimates, progress, and project management.

Where Can We Use This In PHP

Literate Coffeescript does take to an awesome level of making human readable descriptions primary and code secondary. But, unless we go create a new offshoot, how can we use Literate Programming in our code today? I suggest just dropping in Markdown into your comments.

A great place for this is the routes file for your application (or sub-application). Just describe out your todos in a markdown to do list (you can infinitely nest these too). Then you can keep track of your progress as you define your route, and then jump into your controllers and later business logic.

A New Way to Write Routes?

In writing and thinking about this, I have thought about building a route templating language that will let you write literate routes. Using a mix between blade and Literate Coffeescript. This would take in mostly markdown so you can perform Literate Programming similar to Coffeescript. But, it would also allow you to use blade-like syntax to allow you to create routes a bit quicker.

So:

    @get('contact', 'Contact@create')

Would become:

Route::get('contact', 'Contact@create');

Also, lines that would have been parsed as H1 tags will be output as comments in the compiled PHP.

For more information on the syntax, checkout this gist

What do you think? Do you like this syntax? Is it worth building?