Lately I’ve been considering the amount of waste we produce during software development, and how to increase the amount of recycled content. I’m not talking about actual trash, though, but rather about software development artifacts.
Over the years, we’ve learned about and put in practice several means for improving the quality and success rate of projects we create or contribute to. We have practices such as sprints to get people together with high communication bandwidth; we have code reviews for sharing knowledge and improving project quality; we’ve got technical leadership roles to mentor developers and guide the progress of projects; we’ve created kanban boards and burndown charts to help people visualize what they’re going through; and so on.
While all of that seems to have helped tremendously, there’s a sad fact about where we stand: the artifacts of most of these processes are local to their context, and very sensitive to time. That burndown chart is meaningless after it’s burned, and a kanban has no relevant history. Our technical leads indeed guide their teams, but their wisdom stays with the few people that had the chance to interact with them, and subjectively so. That brilliant code review from our best developers has a very limited audience, and rarely carries any meaning just days after it has been accomplished.
That last one is specially interesting. The process of reviewing code is an intense task, very expensive, and that takes a significant portion of the life of an active developer, and even then very little is carried forward as the outcome of that process. We have no effective means or even culture of sharing the generated wisdom to other teams. In fact, we rarely share these details even within the team itself. Why was that line changed like this? Why an interface like that is a bad idea? Who will instruct the new guy next week, and where did we record a bit of the wisdom of the brilliant guy that has left the company recently?
Unfortunately there’s probably no easy solution for this problem. At this point, I mainly recognize that most of the efforts I’ve lead to improve software development for the past several years had a very limited scope. The software itself became immediately better as a result of my efforts, its design became more sensible, and hopefully I contributed a bit to the growth of people around me, but at a company or even community-wide scope, all of these code reviews, sprints, and IRC conversations are buried for very rare revives.
I want to start doing something about this, though. There must be a way to shape these conversations in a more reusable format; in a way that knowledge and agreement can be more proactively preserved and scattered. Perhaps it’s more about how than it is about what. Perhaps we just need to write more posts like this, and cover more topics related to daily development findings. Not sure. I’ll be thinking…
I hear you. However one thing that I did notice with some of the other projects that I have been on is that many of the developers did learn from the code reviews. I spent a lot of time doing thorough reviews of the code and tried to leave reasoning as well as suggested changes. I have found this to be an effective way to transfer knowledge, but I do agree that the audience of any particular code review is very limited – often just being the code author and the reviewer. Another thing I have done as a tech-lead / mentor type is to have a recommended reading list. Whether that be books or sites or other online documents, you can notice as a reviewer when the author has taken on the ideas from the reading, and it is a gratifying time.
I agree with Tim. Code reviews are a good way to teach people, as are reading lists. Most programmers are keen to get better at what they do, and mentoring is a great way to pass knowledge on to someone else.
One problem with code reviews: they become pretty much useless when the bulk of the comments are about trailing whitespace or misplaced curly braces. Code reviews like that easily degenerate into anal-retentive nitpicking that doesn’t actually improve anything. Style comments should be made briefly and as the very last comment in a review session. The point of a code review is not to criticise layout, but point out better designs, algorithms, and find (hopefully not too many) bugs.
The reviewer must be willing to help as much as the “reviewee” must be willing to learn. Egoless programming is important here. Especially with young programmers, there is a tendency to take suggestions for improvement as personal criticism. It is the reviewers responsibility as much as the “reviewee’s” to make sure this does not happen.
Finally, the one thing that most code reviews lack is praise. This is a cultural problem in software engineering in general. People often think that finding flaws in someone else’s work is an achievement, and they derive personal satisfaction from it. (“I’m so much smarter than that guy.”) This can quickly lead to a really hostile environment, where everyone only hears from their colleagues when they point out how they’ve yet again stuffed something up.
Don’t forget to say “I really like the way you did this and that” during a code review. It makes a big difference.
Michi.
I wholly agree with that. And those artefacts span the whole lifecycle of software. Stories in an agile development are often pretty much discarded after a software product has been developed, or at the very least allowed to become stale, even though they form a great description of the system, what it does and what people need it for. Most popular tracking and project management systems tend to encourage that, or do little to help prevent it, since they by design associate stories with a particular release rather than with the product being developed.
Some recent tools for behaviour driven development such as Cucumber, and the whole idea of specification by example have the potential to provide a lasting body of knowledge about a system, and since they are intimately tied to working tests they are more likely to be remain valid and avoid becoming stale.
I started on a open source project called ‘Intensity’ with the intention of providing something that is both usable for day-to-day agile project management and tracking, but can also be used to groom, refine and build a body of knowledge about a system. There is a subtlety to arriving at something that is both flexible and usable enought to support people’s preferred way of working with stories, task, test cases and so on, but also usable in effect as a repository of good quality information – as a tool to harvest and maintain the artefacts that are a side effect of the software development process.
There has been some reasonable success with how Yellow Squad (Gary Poster and his team) have done roughly weekly retrospectives and put up blog posts about it. This at least gives some insight to people outside of the team. I think code reviews are important and helpful, but there is just too much data to be a great way to convey information to 3rd parties.
Then again, blog posts without context can also be hard to absorb. There is still a fair amount of learning that is trial-and-error-and-do-better-next-time.
The first thing I thought of was Rusty’s unreliable guide to locking. I think many software cultures could do with this sort of simple, quite complete document about fundamental, hard yet common problems.
How do we more generally produce these, or, for that matter, know what to produce. Well if everyone is doing their job we’ll get an initial code submission, followed by a (set of) review(s) addressing several points, followed by re-submissions which should include a changelog showing which points were addressed. If we could categorize the review points into types or themes, and score them for importance and correctness (based on whether they were addressed in re-submissions, as well as based on explicit askubuntu style ratings), we might end up with good meta-information for generating useful documents. “7/10 cases where (x) is done this way, everyone agrees to do it that way instead.”