coding/writing for an audience

On page 89 of "Leading Lean Software Development", Mary writes a sidebar on how "writing is very much like programming." While I've been a big proponent of encouraging my teammates to write readable code, I thought it was interesting how Mary takes this to the next level. She describes the thought processes/approach of imagining the reader's needs and multiple drafts/refactoring.

I'm curious to hear from others - do you consider your audience when you code? Do you think you should?

I always consider the audience while coding and try to make the code as readable and understandable as possible for others who will have to read it for example for code reviews or maybe will have to work with my code later. It often makes me a little bit angry if I have to work with my own code some time later and it's hard to understand even for me.

On the other hand I can't understand why lots of (or most?) developers don't even take the time to think about reasonable identifier names etc. other teammates would understand, too. Or some folks who think it's so funny to make code look extra tricky so that even they don't understand it later.

What about the idea with multiple drafts/refactoring? I haven't read the book so I don't really know what you mean.

Usually a pretty boring story about some random business process, but a story nonetheless.

All of my code goes through multiple drafts, although the purpose of any particular draft/refactoring might be different. Sometimes it's just to express something more clearly, sometimes to be more efficient, etc. I also tend to revisit code at arbitrary points in the future, in case my understanding of the problem has changed, or I'm using a new library, or whatever.

David Newton wrote:Usually a pretty boring story about some random business process, but a story nonetheless.

I like this!

Marco Ehrentreich wrote:What about the idea with multiple drafts/refactoring? I haven't read the book so I don't really know what you mean.

I think it was a good analogy. When you write a book/story, you write a draft (or outline), then revise it, then revise it, etc. You don't write the first thing that pops into your head and submit it. Well, unless you are on twitter I guess. Yet when we write code, many people don't proofread it or edit it for readability.

When you write a book/story, you write a draft (or outline), then revise it, then revise it, etc. You don't write the first thing that pops into your head and submit it. Well, unless you are on twitter I guess. Yet when we write code, many people don't proofread it or edit it for readability.

I don't ever expect that the first or even the second draft of the book is what I really intend to say. It is a start. The book evolves into what it eventually turns out to be. It's not just style, it's understanding, ideas, perspective, research, feedback; in a word: learning. All of that happens during the writing / review process, which takes (for a book for me at least) maybe 9-10 months. The book evolves. Yes, it starts with a plan, but not a detailed plan, more like an architecture. Over time the contents emerge.

And I wrote code this way. After all, I was in an electrical engineering department, and process control systems (each one a new one-of system) all evolved this way, so the idea that my process control code was refined over the 10 months or so of a process control system development cycle was just the way control systems were developed.

So why do we worry about software emerging over time when we develop it? This does not mean there is no architecture, it does not mean there is no planning, it means that we acknowledge that learning is a core part of any development process. If authors get to learn, why don't people who write software get to learn?