Colin R. MacDonald has written a good essay about the challenges of giving a task to a junior engineer. As a manager or project lead, I’ve run into pretty much every situation he describes. When it happens on a software project, it can be very frustrating. As Colin describes it with a picture hanging project, it’s quite amusing:
“Why can’t we get a nail gun?”
“We don’t have the budget for it.”
“So we can’t afford to do things right?”
“There’s nothing wrong with driving nails with a hammer.”
“But aren’t we trying to do things better and faster? Are we going to keep using hammers just because we’ve always used them? It’ll pay off in the long run.”
“We don’t spend enough time driving nails around here to justify buying a nail gun. We just don’t.”
Every day I need to make decisions about how much time to spend talking about or writing down the details of a task. You don’t want someone to feel micro-managed, but you don’t want to leave them clueless. Sometimes there’s a surprisingly small difference between the two.
At the moment, I’m leading a team and also writing code for the project, so there’s additional balance between how much time I spend giving direction and how much time I spend on my own work. Its more of an art, than it is a science. I know the project will benefit if I write up checkin guidelines and best practices and write down all that info about the project that is floating around my head, but the project will also benefit from the code I would write in the same amount of time. The larger the team is the more benefit there is for written documents. I find that our culture of frequent code reviews provides a good time for reflection on whether I’ve got the balance right. Live feedback can be fun and low overhead, but if I find myself saying the same things over and over, its time to write them down. Also, no one wants to hear in a code review something that they needed to hear before they started to type.
ok, ok, I’ll go write that best practices document…
well said!
The sad part, as you try to make yourself go write stuff up is that even if you write up your best practices, you still also need to be working with a team that’s mature enough in its sense of software engineering to remember to use the guidelines provided without being stood over. (I gather laszlo is such a place, which is great.)
If an institution has sloppy habits, documentation of proper behavior is just the tip of the iceberg in effecting real change.
It’s true that Laszlo has a really good culture of striving for best practices and following reasonable guidelines. I think the number one thing that keeps us headed in the right direction is frequent code reviews.
We have a policy that all code is reviewed before it gets checked in. Sometimes, at crunch time, minor code changes don’t get reviewed and some code is reviewed post-checkin, but it works well in general. The code reviews accomplish a few very different goals (in order of importance, imho):
1 – Spread the knowledge of the code base. If every check in has a code reviewer, there are always two people who have domain knowledge for fixing any bug.
2 – When you go over the code with someone else, you often see problems that you missed while coding. A code review forces you to review your own code.
3 – The code reviewer can help remind you about coding guidelines and best practices.
It’s easy to get code reviews started because of #1. If someone else reviews your code than you aren’t the only one responsible for it. This aspect appeals to just about every programmer. After people are used to doing code reviews, they usually start to see other benefits.
Interesting. We use code review in my organization and design review. We never have trouble getting people to actually *DO* design reviews and making them successful, but code reviews are harder to make happen.
They tend to happen late in the life of a largish block of code, which I know is part of our problem. Then everybody says “more javadoc, please” and sloughs off doing the real reading.
But if you *had* to check in, say on a feature by feature basis, and you had to do code review for each checkin, it would change the dynamic.
What’s the size of a checkin for your team? How much is a developer asked to review at a sitting? Can you talk about that? Would you mind? I’d love to see an analytical post about the cultural nuts and bolts of this and how you make it work, and I bet a lot of other people would too.
I think we have some good basics where I work for keeping code reviews from getting personal, but we’re not good at making sure they actually happen and making them a necessary event.
Odd to read this article 9 years later. These days I find pair programming more effective than pre-checkin code reviews. When solo work is needed/wanted for various (good) reasons, then I’m fond of the “pair integrations” when you work with someone else for at least a few hours to finish up or incrementally improve some part of the code you just wrote. It is much more active than a code review, which I believe is much more effective and certainly more fun.