John D. Cook blogs a great quotation from G. K. Chesterton that advises caution before removing something. In essence, he challenges people who would remove something unnecessary to go and figure out why it was erected in the first place. Needless to say, this is an issue we deal with a lot in writing software.

In the comments of the post, an interesting debate plays out about the role of code, automated tests, and documentation in helping people figure out why the code that they want to delete was originally written.

Written properly, your code should be self-documenting in terms of its basic workings. Donald Knuth’s literate programming takes this approach to an extreme, but we can move a long way toward it just by naming things well and structuring our programs to emphasize readability. Comments still have their place in areas where efficiency trumps readability, but generally, we should always prefer writing our code so that it’s comprehensible without them.

Unit tests verify that code is functioning properly. They have some use as documentation, but their purpose is to enable you to refactor your code with the assurance that you haven’t broken anything as long as the tests still pass.

Documentation in comments or elsewhere should be the story of why the code works the way it does. Why was a particular algorithm chosen? What compromises did you have to make for performance? What’s likely to fail under strain? These are the sorts of questions that are difficult to answer in the code itself, but are important to anyone who’s expected to maintain the code in the future.

For another take on learning about why things are as they are before making changes, check out my post from last February on getting off to a successful start at a new job. My advice to myself served me pretty well in 2012.

I really liked this post by Camille Fournier, who runs the engineering team for Rent the Runway. When confronted with the problem of giving customers the confidence that the garment they rent will fit properly when it arrives, engineers tend to turn to solutions that involve 3D modeling and “virtual fit assistants.” Unfortunately, real humans are put off by these approaches. The solution they arrived at is much lower tech, but much better for customers. There are two takeaways, I think. The first is that diversity of all kinds on a team is valuable because it leads to a wider variety of proposed solutions to problems. The second thing is that this kind of problem really proves the value of experimentation as a product development approach. Try things and measure the results. You’ll probably wind up being surprised.