2009 March Archive

A snippet site is a website where users post short code snippets that other users can reuse freely in their own projects. A generic example would be DZone, while a more specific example would be this DJango-specific one. Usually, the code is available under a simple license similar to the MIT one although some people do try to cheat the system by adding their own copyright license to their contribution. The problem-solving process which used to work as “look inside the standard library” changes to include “check the main snippet sites” as well, which is a good thing in the everyday fight against casual wheel reinvention.

Snippet websites have a few advantages over standard packaged third party libraries:

There is no complicated install or use process. This can help if the target platform administrators are not under your authority or are not competent enough to install a library. A snippet is usually the code for a single function or class, which can be readily included any programming system. There are often no dependencies on other libraries (unless that is the point of the snippet).
You don’t have to download and install a 25-MiB library for a single function.
By being standalone, the snippet has an interface that only depends on the default value types of the language. This means that, if your program also relies for the most part on those default value types, interoperability will be improved. By contrast, third party libraries can be tempted to define their own types to be used in interfaces.
The snippets also tend to follow the “do one thing and do it well” UNIX philosophy, where there is a single feature in the snippet, and thus the entire development and documentation effort is aimed at making that feature work well. Libraries do many things (because it’s cost-effective for them) which may cause them to be less documented or have a less streamlined design.
Since the snippet is provided in code form and is short enough to be examined, any bugs it contains can be easily detected and corrected by hand, and the corrections can often be “committed” back to the community on that same website.

Of course, there are also downsides to doing so. Libraries are often tested by many people, so bugs are identified more often and re-packaged as new versions. Updating your code to a new library version is usually easier than patching code you downloaded from the internet. And, of course, every idiot on the planet can post a snippet to a snippet site, whereas packaging and distributing a library requires some level of competence.

But the real benefit of snippet sites might well be somewhere else. As much as people who get the snippets from the site gain a lot from it, the developers who post the snippets earn a lot from their posting, even if they give it away for free.

Posting on a snippet site is, by essence, a large-scale software review and testing process. If your snippet contains bugs, is unreadable, badly documented, or badly designed, then the participants on the snippet site will tell you just that—for free. They may post complete minimal examples of how your function fails that you can include in your own unit tests. They may post improvement suggestions that you can follow. They may even provide patches, given an acceptable license policy.
You have to document everything you post on a snippet site, in order to help other users with it. Undocumented code will not be used and will drop to the bottom of the rating pool like a rock. User comments about the snippet are, in essence, additional documentation. Imagine a situation where every class and function in your code base has a dedicated web page where tens of developers rant about what happens in what case, how to use it to accomplish something, what to use in a slightly different situation, or how to troubleshoot something else.
In the average developer, posting to a website creates peer pressure, which counteracts the natural tendency to write sloppy code. Who would write ugly, terse, uncommented code if it was going to be read by hundreds of people? Of course, not every programmer caves in to peer pressure, but a majority of us can still benefit from it.
In order to be snippet-worthy, a class or function has to be reusable. It should make other programmers, who work on completely different projects, to be happy. Therefore, aiming to post on a snippet site implies that the entire development will be about reuse: instead of writing a function that frobnicates your coworker’s foobar, you will be writing a function that frobnicates anyone’s foobar (and anyone’s bazquux as well if they implement a simple interface). This makes sure that every piece in your code does a single thing and does it well, making things easier to reuse, test, debug and document.

In short:

Writing your code as if you intended to post it on a snippet site improves the quality of your code.

Of course, not all code can be posted as snippets. But doing it this way helps separate generic algorithms (those that can be posted as snippets for everyone’s use) from the boilerplate code that represents your project’s logic, and it never hurts to have this separation, especially if said boilerplate code does not contain anything “smart” that’s deserving of analysis or review.

Will there be, one day, a form of snippet-driven development?

You’re a programmer. At work, you and your coworkers have a special company-level account on a public snippet website where you are required to post snippets from your code regularly. The users on that site then rate your code, and your management can then evaluate the quality of your work based on how those users rated you. See your less competent co-workers get flamed away by competent users, and enjoy an improved pay earned from your good ratings! Plus, you’re notified of bugs that appear in your code and get various improvement suggestions every so often.

I sometimes have meta-programs written using C++ templates that have to build a function which performs various tasks. One example would be to create a serialization-deserialization function pair for an object that’s identified as an aggregate of values. Or once could be describing an operation as a series of tags or traits, and the metaprogram must explore those traits and generate the function.

I propose here a small one-file template metaprogramming library that allows the compile-time creation of functions from component sub-functions. First, an example of how it can be used:

#include <iostream>
#include "cacoethes/action.hpp"

struct outer
{
  static void before(int &i)
  { std::cout << "outer::before(" << i << ")n"; ++i; }

  static void after (int &i)
  { std::cout << "outer::after(" << i << ")n"; --i; }
};

struct inner
{
  static void before(int &i)
  { std::cout << "inner::before(" << i << ")n"; i*=3; }

  static void after (int &i)
  { std::cout << "inner::after(" << i << ")n"; i/=2; }
};

using namespace cacoethes;
typedef action::empty<int> action1;
typedef action::decorate<action1, inner> action2;
typedef action::decorate<action2, outer> action3;

int main()
{
  int value = 10;

  std::cout << "Action 1 (" << value << ")n";
  action1::execute(value);

  std::cout << "Action 2 (" << value << ")n";
  action2::execute(value);

  std::cout << "Action 3 (" << value << ")n";
  action3::execute(value);
}

This example outputs, as expected:

Action 1 (10)
Action 2 (10)
inner::before(10)
inner::after(30)
Action 3 (15)
outer::before(15)
inner::before(16)
inner::after(48)
outer::after(24)

The basic principle of the library is as expected: an action is a class that has a static ‘execute()’ function taking a reference to an argument. The function communicates with its caller through that reference, both as input and output.

The simplest action is ‘action::empty’, which is in fact an action template with the type of the argument being a template parameter.

From an action, once can construct another action through decoration. This involves providing a type which has two static functions, ‘before()’ and ‘after()’, both having the same signature as the ‘execute()’ function. The decoration, performed with the ‘decorate<>’ meta-function, creates a new action from the old one. Executing the new action runs the ‘before()’ function, then the ‘execute()’ of the old action, and finally the ‘after()’ function.

Classic errors involve trying to decorate something that is not an action, or trying to decorate using a type that does not have static functions ‘before()’ and ‘after()’.

The “cacoethes/action.hpp” file itself is pretty simple:

// Copyright (c) 2009, Victor Nicollet
// All rights reserved.

#ifndef ACTION_HPP
#define ACTION_HPP

namespace cacoethes
{
  namespace action
  {
    template <typename ARG>
    struct empty
    {
      typedef ARG argument_type;
      static inline void execute(argument_type &arg) {}
    };

    template <typename ACTION, typename OPERATIONS>
    struct decorate
    {
      typedef ACTION inner;
      typedef typename inner::argument_type argument_type;

      static inline void execute(argument_type &arg)
      {
        OPERATIONS::before(arg);
        ACTION::execute(arg);
        OPERATIONS::after(arg);
      }
    };
  }
}

#endif

Nicollet.Net

Monthly Archive for March, 2009

Snippet Sites

C++ Metaprogramming : Actions

New Here? Read These First!

Recent Comments

Recent Ramblings

The Good Old Days