Readable Software

Friday, June 27, 2014

I was trying to decipher a 134 line C# method when frustration struck. How is this mess organized? How did it came to be? Why did the programmer organize it the way he did? When it occurred to me: He didn't. He thought through the logic as he coded, never reflecting on how to make it 'better', which for me as the maintainer translates into 'more readable'. And that is why there is so much WTF in software. The market is for 'mostly' working software, there is no value put on readable, at least not until someone needs to maintain it. Software is like an essay, or a book or any other writing when you view it through the eyes of the maintainer. Any author; or reader, can tell you that if the article is not understandable, it won't be read. Unfortunately as a software engineer, I'm stuck. This piece of code needs to be extended, fixed, enhanced, whatever, and I can't move on to something more interesting or fun to read.

Writing readable software is hard for the same reason that good writing is hard. You must organize and arrange your thoughts in a manner that makes them clear to your reader.

  • You must know your audience.
  • You must organize your thoughts.
  • You must be concise.
  • You must be clear.
  • You must 'mostly' use good style, style that your 'readers' grock.

Just like literature, good software is hard.