of the current plethora of source-code control systems to check out their software to your local machine. While providing such a service is a great thing, providing it poorly is much like setting up a library in the middle of town, throwing all the books up in the air, letting them fall where they may, and then labeling some of them with Post-it Notes. Though most projects are not this horrific, I have noticed a tendency toward several sloppy, and therefore maddening, practices. I blame this trend on the recent introduction of distributed version-control systems, such as Mercurial and Git.

KV’s first rule of public source-tree maintenance is to label everything clearly. Even if you don’t think a tree will last very long, label it: give it a meaning that those who are new to your project can easily understand so they can figure out if that tree is, indeed, of interest to them.

My second rule is to not mix person-
al developer trees with release trees. A
Web page with 100 different possible
checkout targets—and you may laugh,
but I see this on a regular basis—is
not a good way to present your project
to users; nor is it a good way to make
code available. Keeping developer pri-
vate source trees separate from trees
you intend as real releases is a good
way to increase sanity and reduce clut-
ter. If people really need to check out
a developer’s private tree, they’ll likely
find it, though you might help them
along by setting up a page labeled “De-
veloper Trees.”
And lastly, don’t use developer trees
as release trees. If the code in the devel-
oper’s tree is good enough to make a re-
lease, then have the developer check it
in, make a branch, and release it. A de-
veloper who is too lazy to do this should
not be part of a project. No developer is
important or brilliant enough for his or
her tree to be the release tree.

KV
Dear KV,

if the code in
the developer’s tree
is good enough
to make a release,
then have the
developer check
it in, make a branch,
and release it.

being happy and welcoming the extra work, their reactions ran from indifferent to hostile. I even used a popular, open source, embeddable language, not something I cooked up on my own. I made their jobs easier. Why wouldn’t they be happy?

underappreciated

Dear under,

Are you sure you made their jobs easier? Are you sure you understand their jobs? It is a common belief by engineers that every piece of code they write is somehow a boon to mankind and is helping to drive the entire human race forward, propelling us all into a brave new world. Another thing to consider is that most people do not like surprises, even good ones. Try this experiment. Take a $20 bill—or if you’re in Europe a 10-euro note—and leap into a coworker’s cubicle screaming, “Good morning!!!” at the top of your lungs and then loudly slap the bill on the desk. You’ve just given your coworker money, so surely that coworker will be happy to see you. Please report back your results.

What is more likely is that you found
a need that you, yourself, wished to fill
and you spent some enjoyable time
filling that need. There is nothing
wrong with working to scratch a tech-
nical itch; some of the best innovations
come from engineers doing that. There
is something wrong with believing that
a group of people, who have no idea
what you’ve been doing late at night
for the past month, are suddenly going
to look at whatever you’ve created and
say, “Oh, joy! It’s just what I wanted!”
All but the most obvious of creations
need to be socialized. (Yes, I used so-
cialized in a technical column.)

Related articles on queue.acm.org

Purpose-Built Languages

Mike Shapiro

http://queue.acm.org/detail.cfm?id=1508217

Broken Builds

Kode Vicious

http://queue.acm.org/detail.cfm?id=1740550

George V. neville-neil ( [e-mail]) is the proprietor of Neville-Neil Consulting and a member of the ACM Queue editorial board. He works on networking and operating systems code for fun and profit, teaches courses on various programming-related subjects, and encourages your comments, quips, and code snips pertaining to his Communications column.

Copyright held by author.