Great programmers and computer scientists share their views on readability aspect of the code.

1. On Readability of CodeExcerpts from: Peter Seibel, Coders at Work, Apress, 2009. Arun Saha arunksaha@gmail.com October 2009

2. Why these slides? I recently read the book “Coders at work” by Peter Seibel. It is an excellent book containing conversations with fifteen great programmers and computer scientists. One of the issues that came up frequently is, the readability of code. The following slides contain excerpts from the book where the subjects talk about their views on code readability and its importance.

3. Jamie Zawinsky I always wish people would comment more, though the thing that makes me cringe is when the comment is the name of the function rephrased. Function’s called push_stack and the comment says, “This pushes to the stack.” Thank you. You’ve got to say in the comment something that’s not there already. What’s it for? Either a higher-level or a lower-level description, depending on what’s most important. Sometimes the most important thing is, what is this for? Why would I use it? And sometimes the most important thing is, what’s the range of inputs that this expects? Long variable names. I’m not a fan of Hungarian notation, but I think using actual English words to describe things, except for loop iterators, where it’s obvious. Just as much verbosity as possible, I guess.

4. Brad Fitzpatrick Seibel: So when you read good code it either fits into patterns that you already understand, or you’d discover new patterns. But not all code is good. What are the first warning signs of bad code? Fitzpatrick: Well, I’m particularly snooty now, having worked at Google with really strict style guidelines in all languages. On our top six or seven languages, there’s a really strict style guide that says, “This is how we lay out our code. This is how we name variables. This is how we do spacing and indentation, and these patterns and conventions you use, and this is how you declare a static field.” We’ve started putting these online too, just as a reference for external contributors contributing to our projects. We wanted to have a documented policy so we don’t just say, “We don’t like your style.”

5. Douglas Crockford Crockford: .. Another aspect is writing your code such that it can be read. Neatness counts, as it turns out, and style is important. And all of those things will increase the quality of the code base going forward and increase the competence of the programming community. Seibel: What makes code readable for you? Crockford: It happens at a number of levels. The simplest is just being consistent in the presentation so you always indent everything properly; you have white space in all the right places. … That’s the first level, the grammatical stuff. It’s similar to writing in English or any language, getting the punctuation right, getting the capitalization right, putting the commas in the right place. Then you start looking at higher-level things like how you structure the sentences and where you break the paragraphs. In a programming language, it takes the form of how do you decompose the problem into a set of functions or a set of classes?

6. Crockford Seibel: How do you read code you didn’t write? Crockford: By cleaning it. I’ll throw it in a text editor and I’ll start fixing it. First thing I’ll do is make the punctuation conform; get the indentation right; do all that stuff. I have programs that can do that for me, but I find doing that myself is more efficient in the long run because it gets me more acquainted with the code. Seibel: Have you ever found that code that was, at that level, a mess, then you cleaned it all up and discovered it was actually good code underneath? Crockford: I’ve never actually seen that. I think it’s really difficult to write good code in a sloppy manner. By good code, I mean it’s going to be readable. At one level, it doesn’t matter what it does to a machine if I can’t figure out what it does, so it might turn out that the code is amazing in terms of its efficiency, or its compactness, or some other metric which I don’t care about.

7. Crockford Readability of code is now my first priority. It’s more important than being fast, almost as important as being correct, but I think being readable is actually the most likely way of making it correct. So I think it’s probably not good code and they probably made the wrong trade-offs if the code turned out to be in the state that it’s not easily readable. Seibel: Do you consider yourself a scientist, an engineer, an artist, a craftsman, or something else? Crockford: I think of myself as a writer. Sometimes I write in English and sometimes I write in JavaScript. It all comes down to communication and the structures that you use in order to facilitate that communication. Human language and computer languages work very differently in many ways, but ultimately I judge a good computer program by its ability to communicate with a human who reads that program. So at that level, they’re not that different. Seibel: And if it can communicate well to a human, you feel like the communicating-with-the-computer part will fall out? Crockford: You hope so. Computers are arbitrary and not very smart, so you have to make special efforts to make sure that they get it. Because that’s so hard, it’s easy to overlook the other part, but I think it is at least as important.

8. Joshua Bloch Bloch: Generally speaking, I find that, contrary to popular belief, the cleaner and nicer the program, the faster it’s going to run. And if it doesn’t, it’ll be easy to make it fast.As they say, it’s easier to optimize correct code than to correct optimized code. Bloch: I will cheerfully spend literally hours on identifier names: variable names, method names, and so forth, to make my code readable. If you read some expression using these identifiers and it reads like an English sentence, your program is much more likely to be correct, and much easier to maintain. I think that people who say, “Oh, it’s not worth the time; it’s just the name of a variable,” just don’t get it. You’re not going to produce a maintainable program with that attitude.

9. Bloch Bloch: As I write the program, I say to myself, what it is that must be true here? And it’s very important to put those assertions into the code, to preserve them for posterity. If your language lets you do it with an assert construct, use it; if not, put assertions in comments. Either way, the information is too valuable to lose. It’s what you need to understand the program six months down the road, and what your colleague needs to understand the program any time at all.

10. Bloch My natural tendency to believe that simple is good has been reinforced. Over and over I see additions that are more complex proving themselves to be detrimental in the long—or short—run. When I’m designing stuff, I pay close attention to my “complexity meter:” when it starts bumping into the red zone, it’s time to redesign stuff. I’ve occasionally run into people who just don’t believe that, who just say, “Well, you’re stupid, Josh, you just don’t get it; this is the right way to do it and I’m sorry if you don’t understand it.” I just don’t buy that. I think that if things start getting complicated, there’s probably something wrong with them and it’s probably time to start looking for an easier way to do it. There’s a brilliant quote by Tony Hoare in his Turing Award speech about how there are two ways to design a system: “One way is to make it so simple that there are obviously no deficiencies and the other way is to make it so complicated that there are no obvious deficiencies.”

11. Joe Armstrong I like documentation. I don’t think a program is finished until you’ve written some reasonable documentation. And I quite like a specification. I think it’s unprofessional these people who say, “What does it do? Read the code.” The code shows me what it does. It doesn’t show me what it’s supposed to do. I think the code is the answer to a problem. If you don’t have the spec or you don’t have any documentation, you have to guess what the problem is from the answer. You might guess wrong. I want to be told what the problem is.

12. Armstrong Seibel: Are there other skills that are not directly related to programming that you feel have improved your programming or that are valuable to have as a programmer? Armstrong: Writing is. There’s some computer scientist that said, “Oh, if you’re no good at English you’ll never be a very good programmer.” Seibel: I think Dijkstra had something about that.

13. Peter Norvig Seibel: A (lot) of companies say they should do reviews but it’s very rarely followed through on. You must, at some level, train people how to do that. Norvig: I think it was something that had always been done and so people accept it. Well, I shouldn’t say that completely. Some people it takes a while to get used to it. One of the typical failure cases is a new hire comes in and they’re not used to doing this kind of thing so they just start an experimental branch and they have all their code in there and you keep on telling them, “Gee, you don’t have any check-ins yet.” And they say, “Yeah, yeah, yeah, I’m just cleaning it up—I’ll check it in tomorrow.” And then another week goes by and another week goes by and eventually they have this one gigantic check-in. And then it’s a problem that too much time has gone by, it’s hard to evaluate it all at once, and some of the things they’re comparing against have changed out from underneath them. Then they see what a headache it is and they learn not to do that..

14. Guy Steele Seibel: So do the lessons of writing English for a human reader help you with that aspect of code? Steele: Well, sure. When I’m writing code, one of the foremost things in my mind is, will this get the computer to do what I want? And so it’s a matter of, “Will it be understood even one way?” Rather than not at all. Then there’s the question of often there’s more than one way to write something correctly. And at that point I begin worrying about the human reader. And I also worry about efficiency. There’s a trade-off there, typically. If efficiency is important, I’ll often resort to a trick. And then I realize that will mislead a human. And you have to comment it or do something to flag that, to make it more readable. But yes, very often in things like choices of variable names and the way code is laid out and so forth, the emphasis is more on the human reader, and you think about how you can use details of the code formatting that don’t matter to the computer to provide the necessary signals to the human reader.

15. Steele Seibel: Since you just mentioned Design by Contract, how do you use assertions in your own code? Steele: I have a tendency to drop in assertions, particularly at the beginnings of procedures and at important points along the way. And when trying to—maybe “prove” is too strong a word—trying to justify to myself the correctness of some code I will often think in terms of an invariant and then prove that the invariant is maintained. I think that’s a fruitful way to think about it.

16. Bernie Cosell The binary bits are what computers want and the text file is for me. I would get people—bright, really good people, right out of college, tops of their classes—on one of my projects. And they would know all about programming and I would give them some piece of the project to work on. And we would start crossing swords at our project-review meetings. They would say, “Why are you complaining about the fact that I have my global variables here, that I’m not doing this, that you don’t like the way the subroutines are laid out? The program works.” They’d be stunned when I tell them, “I don’t care that the program works. The fact that you’re working here at all means that I expect you to be able to write programs that work. Writing programs that work is a skilled craft and you’re good at it. Now, you have to learn how to program.”Some of these guys were fabulously good programmers and they’d never once read a line of anybody else’s code. In fact, some of them never even read their own code, so they never had the pain of seeing what happens six months later.

17. Cosell Seibel: What about the tension between clarity and efficiency? Sometimes the simplest, easiest-to-read code isn’t the fastest. Cosell: Programmers are the worst optimizers in the world. They always optimize the part of the code that’s most interesting to optimize, and almost never get the part of the code that actually needs optimization. So you get these little nuts of very difficult code that have no point. I always tell the people working with me, “Code it as lucidly, as easy to read, as crystal clear as you can. Do it the simple way. And then if it needs to be sped up, we’ll deal with that later. If you’ve done it right, we can draw a little box around this piece.”

18. Feel free to share your opinion. Thank you!