Comment driven development

There is quite a handful of programming techniques out there; TDD, BDD, YAGNI, DRY to name a few. This post will be about something many people might already be doing but don’t know it has a name: Comment-driven development or comment programming.

CDD is helpful for:

  • prototyping,
  • spitting out your thoughts in code editor, so you don’t forget anything later (good for brainstorming sessions),
  • explaining what needs to be done if someone else is going to be writing the code itself,
  • commenting the code :). Comments could remain, so your code is documented from the get-go

I often start the new PHP file or class or even method with the layout in comments. Here’s an example:

// Get the needed models
// Collect todo items
// Get lists that the todo items belong to
// Send to View

Ok, everything is clear. After the real code sets in it looks like this:

public function someAction()
{
    // Get the needed models
    $todoTable  = new TodoTable();
    $listTable  = new ListTable();
 
    // Collect todo items
    $todos      = $todoTable->findByAuthor($author);
 
    // Get lists that the todo items belong to
    foreach ($todos as &$todo) {
        $todo['lists'] = $listTable->find($todo['list_id']);
    }
 
    // Send to View
    DIC::get('View')->todos = $todos;
}

As you can see, the comments can stay in place. Even for this simple example, it is good practice to document your code.

The Wikipedia article states:

In comment programming the comment tags are not used to describe what a certain piece of code is doing, but rather to stop some parts of the code from being executed. The aim is to have the commented code at the developer’s disposal at any time he might need it.

And later on:

However, comment programming is used instead of a real implementation. The idea is that many functions can be written like this, and then the design can be reworked and revisited without having to refactor a lot of source code.

So, Wikipedia article is somewhat contradictory to itself. The aspect of comment programming I am writing about here is the “comments instead of a real implementation” part.

Do you write your code with comments first approach? Do you use some other technique?

  • Comments win the internet. Commented code is easier to maintain, improve, figure out – no downsides unless you write shitty unreadable comments or comment too much (every line).

    I use similiar technique – first a rough sketch of what I’m trying to do, then some pseudocode, then write small blocks that connect to a bigger ‘picture’. Then if needed, small blocks that could be reused at a later point – functionize or methodize™. :D