4 ms·

I once had a developer who consistently wrote unreadable code while trying to be clever. To give him useful feedback I needed to come up with a black and white

I once had a developer who consistently wrote unreadable code while trying to be clever. To give him useful feedback I needed to come up with a black and white heuristic for knowing if code is readable or not. The heuristic is this: Readable code can be explained in English sentences in one pass. Your code tells a story. When you read it do you introduce the characters in the right order? Halfway through a complex passage do you reference something out of context without explaining it? Give concepts valid names to help the reader build context on your intent. The best part of this heuristic is that you can get the code author to attempt to read back their own code, and trip over their own convolutions, and realize where there is opportunity to simplify. We all worked on the same codebase so a reasonable shared understanding of the concepts was assumed. This blog post throws various situations into the mix to try to be contentious or something but misses the point.

deleted 9y ago
[deleted]
JoeAltmaier 9y ago
Fits with my thought: code should be systematic. A collection of unrelated bits put together as by a committee is hard to read.
gregjor 9y ago
That's called the telephone test. From The Elements of Programming Style (referenced in my article): "Use the telephone test for readability. If someone could understand your code when read aloud over the telephone, it's clear enough. If not, then it needs rewriting." I agree that the telephone test heuristic gives you an idea of readability, but in 1974 Kernighan and Plauger assumed someone one the other end of the phone who knew Fortran or PL/I. Trying to explain a moderately complex class hierarchy or a factory function or a closure over the phone would prove challenging. I could explain the purpose of the code at a level someone else could understand, but they might not recognize the implementation when looking at the code. A few years ago, doing maintenance on an abandoned production system, I came across a function with the comment "Produce a unique six-digit identifier that doesn't start with 0". The original programmer could have explained that to me over the phone, but his implementation (in PHP) was not clear at first or second glance. I expected this: $id = rand(100000, 999999); Instead the function started with a loop to get the first digit: while (true) { $first = rand(0, 9); if ($first != 0) break; } I'm not making this up. Then another loop to pick five more digits in the range 0..9. Then a database query to see if that ID was used, and if it was the function called itself recursively. I'm not kidding. So while I would have understood the problem described over the phone, I didn't recognize the implementation at first sight. If the programmer had read the code to me over the phone I might have assumed I was missing some requirement that led to this overly-complicated implementation. Not all of the code looked like this so I don't know how the original programmer got wound around the axle on this function.
dboreham 9y ago
I've always used this approach to coding : 1. Write in English what you intend the code to do, as comments. 2. Progressively write code to do what you said you would do above until it is all done. 3. Leave the comments there to explain what it does. I've worked this way since I got to use comments (originally I coded in hex, computing negative branch offsets in my head as I went -- possibly this explains why I'm such an curmudgeon about requiring comments that explain any non-obvious code's purpose and intentions). (Yes there is an issue with consistency between comments and code, especially if code is changed over time. Better to fight that problem I believe than to have no information from the original developer as to wtf they thought they were doing.)

deleted 9y ago

[deleted]

JoeAltmaier 9y ago

Fits with my thought: code should be systematic. A collection of unrelated bits put together as by a committee is hard to read.

gregjor 9y ago

That's called the telephone test. From The Elements of Programming Style (referenced in my article): "Use the telephone test for readability. If someone could understand your code when read aloud over the telephone, it's clear enough. If not, then it needs rewriting." I agree that the telephone test heuristic gives you an idea of readability, but in 1974 Kernighan and Plauger assumed someone one the other end of the phone who knew Fortran or PL/I. Trying to explain a moderately complex class hierarchy or a factory function or a closure over the phone would prove challenging. I could explain the purpose of the code at a level someone else could understand, but they might not recognize the implementation when looking at the code. A few years ago, doing maintenance on an abandoned production system, I came across a function with the comment "Produce a unique six-digit identifier that doesn't start with 0". The original programmer could have explained that to me over the phone, but his implementation (in PHP) was not clear at first or second glance. I expected this: $id = rand(100000, 999999); Instead the function started with a loop to get the first digit: while (true) { $first = rand(0, 9); if ($first != 0) break; } I'm not making this up. Then another loop to pick five more digits in the range 0..9. Then a database query to see if that ID was used, and if it was the function called itself recursively. I'm not kidding. So while I would have understood the problem described over the phone, I didn't recognize the implementation at first sight. If the programmer had read the code to me over the phone I might have assumed I was missing some requirement that led to this overly-complicated implementation. Not all of the code looked like this so I don't know how the original programmer got wound around the axle on this function.

dboreham 9y ago

I've always used this approach to coding : 1. Write in English what you intend the code to do, as comments. 2. Progressively write code to do what you said you would do above until it is all done. 3. Leave the comments there to explain what it does. I've worked this way since I got to use comments (originally I coded in hex, computing negative branch offsets in my head as I went -- possibly this explains why I'm such an curmudgeon about requiring comments that explain any non-obvious code's purpose and intentions). (Yes there is an issue with consistency between comments and code, especially if code is changed over time. Better to fight that problem I believe than to have no information from the original developer as to wtf they thought they were doing.)