Posted by aogTuesday, 02 February 2010 at 13:38 TrackBack Ping URL

Inspired by Skipper’s belief in self documenting code I thought I might start dropping in some little tidbits I generate as I go about my code slinging day.

Today’s little gem is this —

bool
Clause::visit(visitor const& v, int depth) {
    return ! (! _d || ! v(depth, *this) || ! this->visit_children(v, depth));
}

The Clause class is a unit in an expression. The visit method takes a function object v and invokes it on the clause and every nested clause (as long as the function object returns true), an implementation of the standard visitor pattern. I have split this method in to two, visit and visit_children because in some cases I do want to visit on the children of a clause and not the clause itself. The _d is a member variable of the class (I use the leading ‘_’ as my typographic indicator for member variables) which holds the actual data in the class. I would argue that even if you know all of this, and you are familiar with C++, the purpose of this code is not immediately obvious. I would say a short comment about the thought processes that lead to this code would be appreciated by anyone else trying to figure it out.

I will admit that well chosen method names can help but they’re hardly sufficient.