Comments on: Proof reading is more important than composition

By: Coding conventions are a precondition to readability « AJ’s blog

Coding conventions are a precondition to readability « AJ’s blog — Sat, 06 Jan 2007 21:14:05 +0000

[...] About the same time I stumbled over an article that pointed to “Proof reading is more important than composition“. The authors opinion about readability is something to applaud. All the more irritating how wrong his conclusions are (just my opinion of course!). He deprecates coding conventions as being of adverse effect for readability. Having worked on software in teams of up to 80 developers and of different age (in terms of versions and maintenance impact) I am accustomed to read and evolve existing code as well as write code that has to be understood by other developers after I have moved on. And of one thing I am certain: Coding conventions are a necessary requirement for readability. Of course they are not sufficient, but do away with them and readability will follow shortly. All it needs is the next developer working on the code and using his personal coding style. This has to happen only once, no way to put the chicken back in the egg. [...]

By: Assaf

Assaf — Thu, 07 Dec 2006 03:37:51 +0000

other people’s code tend to be less readable than yours, so as a team you’re going to learn much more about writing readable code that other people can maintain, if you pay attention to your own hesitation reading other people’s code.

and gradually you’ll end up converging on some common coding style, I personally always pick on the style of whoever wrote the most code.

By: GBS

GBS — Tue, 05 Dec 2006 20:45:20 +0000

And what about programming on a team? Where there are 4 or 5 developers whose hands have touched (and will touch) the code base.

By: James Taylor

James Taylor — Sun, 03 Dec 2006 22:15:07 +0000

But what if you want non-programmers to read the “code”? How about finding the pieces of code you change all the time or explain all the time and coding them in something more accessible like business rules.

By: Assaf

Assaf — Sun, 03 Dec 2006 21:07:28 +0000

This is actually something I learned from writing (not code). No matter how well you write, you’re still going to make a lot of mistakes. Editing is very important, I edit each post at least twice before it’s good enough to make it out there.

And I don’t bother writing well at all. I only care about editing it well, before hitting the publish button. I focus on reading and judging how it reads.

As a result I spent a lot of time editing what I write. But that’s no longer the case, because the brain picks up and improve and each editing makes you a better writer. You get that training for free.

If you practice your editing, you don’t have to practice your composition. Even better, when you get in the habit of scrutinizing what you read, you can easily pick up ideas and tips from reading other people.

Once I stopped practicing my composition skills, I became a much better writer. With text and with code.

By: Crosbie Fitch

Crosbie Fitch — Sun, 03 Dec 2006 19:57:36 +0000

Even for solo coders, a coding convention can be very helpful.

I often think lazy handwriting is fine given only I read it, but then n months down the line I can’t figure out what gems I wrote.

Clarity in composition helps coherence in coding.

The more carefully you code the less likely it is that you will ever need to re-read that code – precisely because it has fewer bugs in it. The discipline of a coding convention isn’t just for the benefit of the reader’s comprehension, but also the writer’s – at the time they’re writing it.

But, anyway, wisdom cannot be taught – it has to be learnt.

Therefore it may well be good advice to all new coders, to avoid use of coding conventions (except in collaborative works) until they appreciate for themselves whether they are useful.

By: Chipping the web - 00001111 -- Chip’s Quips

Chipping the web - 00001111 -- Chip’s Quips — Sun, 03 Dec 2006 00:39:14 +0000

[...] Assaf offers a maxim for keeping code maintainable: When re-reading, fix where you hesitate. [...]

By: Assaf

Assaf — Sat, 02 Dec 2006 21:10:10 +0000

I think coding conventions conflict with it, not the other way around. It gives people the wrong thing to focus and a plan that assumes it will be written right to begin with.

But if you have people working on the same code base, and fixing everything that doesn’t look right, eventually you converge on a common convention.

By: beza1e1

beza1e1 — Sat, 02 Dec 2006 14:10:47 +0000

You approach “lazy writing for readability” doesn’t conflict with coding guidelines. Why shun the guidelines?

By: Assaf

Assaf — Sat, 02 Dec 2006 09:27:22 +0000

It's a pun on the ninety-ninety rule. In practice it actually takes 180% of the time, and I only get 90% of the functionality, because at 110% features start falling off the project plan.