Monday, February 13, 2006
On another note
A couple of weekends ago I was pleasantly surprised to bump into Steve Freeman at a very English institution. Steve came up with a parallel between the way that orchestral players mark their parts in pencil, and the way people comment their code. With orchestral scores, each player and conductor has their own interpretation of the piece. They often mark their parts in pencil to remind them of changes of tempo, changes of key, or when the pages need turning quickly. As sets of parts get passed from one player or orchestra to another, the amount of pencil tends to increase, often obscuring the original information. It is normally a relief to see a nice clean part with little or no pencil, just the notes and directions as written by the composer. Removing the clutter gives time and space to read and process all of the information on the page, without confusion, contradiction or duplication of information.
People often encourage thorough commenting of code, to explain to other developers what it does, and how it works. Steve and I reckoned that we would much rather see clear, well written code with no comments, than the verbose and largely unhelpful comments that one often sees. Then when you do see a comment, you know to pay particular attention to it. We really want to see the notes underneath the pencil, not be distracted by scribbles.
People often encourage thorough commenting of code, to explain to other developers what it does, and how it works. Steve and I reckoned that we would much rather see clear, well written code with no comments, than the verbose and largely unhelpful comments that one often sees. Then when you do see a comment, you know to pay particular attention to it. We really want to see the notes underneath the pencil, not be distracted by scribbles.
