aspose file tools*
The moose likes Agile and Other Processes and the fly likes coding/writing for an audience Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login
JavaRanch » Java Forums » Engineering » Agile and Other Processes
Bookmark "coding/writing for an audience" Watch "coding/writing for an audience" New topic
Author

coding/writing for an audience

Jeanne Boyarsky
author & internet detective
Marshal

Joined: May 26, 2003
Posts: 31074
    
232

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?


[Blog] [JavaRanch FAQ] [How To Ask Questions The Smart Way] [Book Promos]
Blogging on Certs: SCEA Part 1, Part 2 & 3, Core Spring 3, OCAJP, OCPJP beta, TOGAF part 1 and part 2
Marco Ehrentreich
best scout
Bartender

Joined: Mar 07, 2007
Posts: 1282

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.

Marco
Jelle Klap
Bartender

Joined: Mar 10, 2008
Posts: 1836
    
    7

"Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live."

So, yes


Build a man a fire, and he'll be warm for a day. Set a man on fire, and he'll be warm for the rest of his life.
David Newton
Author
Rancher

Joined: Sep 29, 2008
Posts: 12617

I try to let my code tell a story.

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.
Jeanne Boyarsky
author & internet detective
Marshal

Joined: May 26, 2003
Posts: 31074
    
232

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.
Mary Poppendieck
author
Ranch Hand

Joined: Oct 04, 2006
Posts: 62
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?


Mary Poppendieck
Author of Lean Software Development, Implementing Lean Software Development, and Leading Lean Software Development
David Newton
Author
Rancher

Joined: Sep 29, 2008
Posts: 12617

Mary Poppendieck wrote:If authors get to learn, why don't people who write software get to learn?

Bosses.
Mary Poppendieck
author
Ranch Hand

Joined: Oct 04, 2006
Posts: 62
Bosses.
'' Wise bosses know better.
Marco Ehrentreich
best scout
Bartender

Joined: Mar 07, 2007
Posts: 1282

Bosses.

I wish it would be only bosses
 
I agree. Here's the link: http://aspose.com/file-tools
 
subject: coding/writing for an audience