Branching Privately

Irrespective of the number of meetings attended or PowerPoint slides produced, developers communicate in one language, and one language only – the language of code. In many organisations trunk, or centrally hosted branches, give visibility of the work going on. This keeps everyone in the loop as to what is being developed, how its being done, and by whom.

Moving away from this work flow, towards teams working in local branches away from prying eyes, cuts this information flow. The development effort in these branches, now lacking the exposure to more than the team working on it, could miss out on vital feedback from other team members. Team member, that had the work been done centrally, allowing them to see what was happening, could have given feedback. This could have saved the team weeks or months of effort had they known that code already existed over here, or this team requires that module to do that as well, so don’t duplicate effort. These issues won’t be discovered until the big bang, the merge back into the mainline.

Large Changesets

Branches, by there very nature result in larger changesets being pushed back into the mainline. This can also be true when working on the main branch, but on a local repository. There can also be a temptation to complete a full feature before pushing the changes to the mainline. Developers will still be commiting their code in small changesets, but without giving it that push upstream to the mainline many benefits are lost.

Committing a feature little by little has many benefits. I’ve already mentioned peer review when talking about branching. In addition to this it allows detection of regressions to be detected as early as possible, making them easier to locate. Putting code into the mainline in feature size chunks certainly result in making it easier to track which changeset caused a regression, as there will be less of them. But finding which part of that feature sized changeset caused the regression will not be so easy.

Enjoy responsibly

Distributed soruce control management systems give us great power, but remember with great power comes great responsilbity.

Smells

If your not familiar with the idea of code smells, the be sure to check out Martin Fowlers excellent book Refactoring: Improving the Design of Existing Code. Code smells are symptoms in your source code that can indicate problems – arguably the worst being code duplication which violates the principles of DRY.

The code maintenance issues are well known,  so I won’t revisit them here. What I want to do is talk about a tool I found the other day that helps find duplicate code.

Copy Paste Detection (CPD) is a great little program that can detect duplicate code in a code base.  Its available under a BSD-style licence, shipped as part of the PMD static code analyzer for Java. Although PMD is targeted as java, as CPD works using string matching, it can be used on any language.  Java, JSP, C, C++, Fortran and PHP are supported out of the box. It is also possible to add further langugages.

How to use it

Running CPD is very simple:

./cpd.sh ~/path/to/source/

And thats it. By default the output is in text format, this can be changed to xml or csv. Example output of processing the JDK (reported to take only 4 seconds) can be seen here. The number of duplicate tokens require for code to be considered copy and pasted can also be configured, this defaults to 100.

My findings

I had to increase the heap size available to java to get the code based I’m working on parsed. Its about a million lines of C/C++ code. There results were fascinating.  Sure enough, copy and pasted code was found, comments and all. Worse still, code that had been copy and pasted but not quite kept in sync, in most cases straight bugs.

The only real false positives I found were with auto generated code. By default CPD recursively parses the directories (you can supply as many as you like) on the command line, without being able to ignore certain files (eg *_autogen.cpp). As these files are produced as part of the build process, I’m now running CPD on a clean checkout, without build any build artifacts lying about.

What next?

As always with these things, I’m left with a bunch of open questions:

I can see this tool can offer some real value, but how do I integrate it into my teams work flow? Its a command line tool only, so there is no administration interface to allow results of various runs to be compared and analysed.

There are plenty of other static code analyzers that do much more than just check for duplication, what are peoples experiences with these?

It’s very easy to point out whats wrong with code. Pointing out how the design and implementation of the code we’re working with is making our lives hard. Talking with fellow programmers about how our hands are tied and how we “did what we could” given that it “wasn’t our code”.

This all too familiar discussion demonstrates what I call the maintenance programmer mindset.

Are you too stuck in this mindset? Its very easy to fall into.

I have to remind myself regularly to break out of this mindset; to be bolder, to have the confidence to change the direction the code is heading. To make a clear statement about the problem domain by introducing a new class. To factor out that bit of repeated code into its own method. To break that monolithic module into two more focused modules to regain control over dependencies. To grab the wheel and make the kind of changes that steer the design down the correct path. The requirements on an active software project change constantly, so the design must also.

It’s quite easy to see if someone is stuck in this mindset. The following are a list of the actions that make a statement about the direction a code base is heading, in order of impact and are unlikely to be performed by sometime stuck in this mindset.

• Adding new new module/package
• Adding a new class
• Adding a new source file
• Adding a new function

If your not doing most of the above on a regular basis, irrespective of if your maintaining software or doing green field development – your programming with the maintainance programmers mindset.

Readability

Looking at the call site when invoking an overloaded function its not immediately obvious which method is being called.

find("code buddy");
find(C_PLUS_PLUS);

After a quick look through the overloading options available I can always work out which one will be called – but why should I? If code is making me think more than is absolutely neccessary then for my money, there is an issue with it. Wouldn’t the previous code be clearer if it was written like this:

findByName("code buddy");
findByLanguage(C_PLUS_PLUS);

Tags

My poor tags get confused! I’m working in a C++ code base on a linux OS. Rightly or wrongly, I’m using emacs with cscope as my chosen editing/tagging solution.  For example, if I’m working with the Visitor Pattern that is using overloading for its visit method, as search for:

void visit(const NodeA& node);

also finds me:

void visit(const NodeB& node);
void visit(const NodeC& node);

This maybe a shortcoming of cscope, however I’ve seen other tagging solutions, notably the one used in Slick Edit fall at the same hurdle.  I’d much rather see this visitor interface written like this:

virtual void visitNodeA(const NodeA& node) = 0;
virtual void visitNodeB(const NodeB& node) = 0;
virtual void visitNodeC(const NodeC& node) = 0;

Templates

It maybe nessary for templatised code that you use overloading, eg:

template<Node>
void doSomeStuffAndVisit(IVisitor& visitor,
                        const Node& node)
{
    // some code
    visitor.visit(node);
    // some more code
}

Constructors

Overloading of constuctors is unavoidable.

// Creates a Foo from the xml in file file
Foo::Foo(const std::string& file);
 
// Creates a Foo from the xml node root
Foo::Foo(const xmlNode& root);

Unless of course your using a factory method, in which case, there is no need to overload like this:

// Creates a Foo from the xml in file file
*Foo FooFactory::createFoo(const std::string& file);
 
// Creates a Foo from the xml node root
*Foo FooFactory::createFoo(const xmlNode& root);

The comments really are the give away here, taking the comments away things become so much more readable.

FooFactory::createFooFromFile(const std::string& file);
 
FooFactory::createFooFromXMLNode(const xmlNode& root);

Conclusion

These days, unless I’m working with any code thats using templates, i’m avoiding overloading, the pros are much outweighed by the cons.