Leslie Lamport on thinking first and on commenting code (2007)

From an interview by Mihai Budiu:

> The fundamental idea behind verification is that one should think > about what a program is supposed to do before writing it. Thinking is > a difficult process that requires a lot of effort. Write a book based > on a selection of distorted anecdotes showing that instincts are > superior to rational judgment and you get a best seller. Imagine how > popular a book would be that urged people to engage in difficult study > to develop their ability to think so they could rid themselves of the > irrational and often destructive beliefs they now cherish. So, trying > to get people to think is dangerous. Over the centuries, many have > been killed in the attempt. Fortunately, when applied to programming > rather than more sensitive subjects, preaching rational thought leads > to polite indifference rather than violence. However, the small number > of programmers who are willing to consider such a radical alternative > to their current practice will find that thinking offers great > benefits. Spending a few hours thinking before writing code can save > days of debugging and rewriting. > >

The idea of doing something before coding is not so radical. Any number of methods, employing varying degrees of formalism, have been advocated. Many of them involve drawing pictures. The implicit message underlying them is that these methods save you from the difficult task of thinking. If you just use the right language or draw the right kind of pictures, everything will become easy. The best of these methods trick you into thinking. They offer some incentive in the way of tools or screen-flash that sugar coats the bitter pill of having to think about what you’re doing. The worst give you a happy sense of accomplishment and leave you with no more understanding of what your program is supposed to do than you started with. The more a method depends on pictures, the more likely it is to fall in the latter class.

At best, a method or language or formalism can help you to think in one particular way. And there is no single way of thinking that is best for all problems. I can offer only two general pieces of advice on how to think. The first is to write. As the cartoonist Guindon once wrote, “writing is nature’s way of showing you how fuzzy your thinking is.” Before writing a piece of code, write a description of exactly what that piece of code is supposed to accomplish. This applies whether the piece is an entire program, a procedure, or a few lines of code that are sufficiently non-obvious to require thought. The best place to write such a description is in a comment.

People have come up with lots of reasons for why comments are useless. This is to be expected. Writing is difficult, and people always find excuses to avoid doing difficult tasks. Writing is difficult for two reasons: (i) writing requires thought and thinking is difficult, and (ii) the physical act of putting thoughts into words is difficult. There’s not much you can do about (i), but there’s a straightforward solution to (ii) — namely, writing. The more you write, the easier the physical process becomes. I recommend that you start practicing with email. Instead of just dashing off an email, write it. Make sure that it expresses exactly what you mean to say, in a way that the reader will be sure to understand it.

Remember that I am not telling you to comment your code after you write it. You should comment code before you write it.