Writing code is writing

Introduction

I may be a programmer, but I’m also an avid reader of non-technical books (commonly know as “fiction”. Having done some (sufficiently bad to stay in the secret of my PC) attempt at writing, I use to take a look at the advice professional or successful writers do give.

Some of them made me think that writing code being, after all, writing, some of those advices are probably sound regarding writing code, even if they were made originally regarding natural language (commonly know as “English”).

Advices

Writing

“Write.” – Neil Gaiman

Cover of Neverwhere

Probably the simplest, but also the most potent advice. If reading books, following courses and blogs can help you become better, nothing will ever replace practice. The best way to learn to code is to code. Same for improving. It may seems silly, but it’s not (how many of us read a little each day, and how many find this same time to code a little?).

I happen to really like Neil Gaiman’s books. I would recommend “Neverwhere” as a start.

“The way to write a book is to actually write a book. A pen is useful, typing is also good. Keep putting words on the page.” – Anne Enright

Putting this in our coding context, what I like is again the emphasis on the “do” part, and a simple sentence that says a lot about tools: they are helpful, but they are just that – tools. Pick one that works for you. Remind me of the never ending IDE debate (did I already said how much I like Sublime Text and Eclipse, by the way? ).

“Do it every day. Make a habit of putting your observations into words and gradually this will become instinct. This is the most important rule of all and, naturally, I don’t follow it.” – Geoff Dyer

Again, one step further: do it, pick your tools and now do it every day. This is the discipline lesson, one hard to follow, but that brings immense benefits: “gradually this will become instinct”.

Reading

On Writing (Photo credit: Wikipedia)

“Read a lot, write a lot” Stephen King

Even if you need to concentrate to your own problem to solve, looking at others code will improve your own. I’m not talking about something specific (like look how other people do solve the problem you have), but in a very generic way: reading people’s code will make you a better programmer. It expands your horizon. While I’m not fan of Stephen Kings’ books, his take on being a writer is superb and aptly named “On writing” – as is this post, for totally related reasons.

“The reader is a friend, not an adversary, not a spectator.”Jonathan Franzen

We should put this in large-sized letters on each programmer’s office’s wall. You are not writing code for the sheer sake of it. Contrary to popular belief, code primary target is not the machine: it is another programmer (which may be yourself in a few months). In this point of view, Jonathan Franzen’s advice is golden: think of the reader as a friend means treating him as such by making his reading a nice experience, and seeing his pair of eyes as something that helps, not hinders you.

Reviews

“ Remember: when people tell you something’s wrong or doesn’t work for them, they are almost always right. When they tell you exactly what they think is wrong and how to fix it, they are almost always wrong.” – Neil Gaiman

This is probably the mindset we need when discussing our code with someone: not rejecting the vague “I do not like this part”, even without solid arguments. If your reviewer is experimented or familiar with your work and that something makes him itch, there is probably something. On the other side, be careful about the amount of “you should rather do this this way”. Not that they are never true, just that help with the problem is often more valuable than with the solution.

“Write with the door closed, rewrite with the door open. Your stuff starts out being just for you, in other words, but then it goes out. Once you know what the story is and get it right — as right as you can, anyway — it belongs to anyone who wants to read it. Or criticize it.” – Stephen King

In my words: code is (should be) a collective production. Of course each part starts being only one person’s work, but bringing people do not means only taking advices. It means making something that was “yours” something that will be “ours”. If you’re not ready for that, then you are not really ready to take advices.

Refactor

“Do change your mind. Good ideas are often murdered by better ones. “ – Roddy Doyle

 

The Private Patient (Photo credit: Wikipedia)

How many time did we experience this? Ponder a design, explore, test, get something you are happy with, let it repose for a couple of day. You’ll often discover that the experience made you able to see a better way. Maybe we should murder more designs.

“Fix it. Remember that, sooner or later, before it ever reaches perfection, you will have to let it go and move on and start to write the next thing. Perfection is like chasing the horizon. Keep moving.” – Neil Gaiman

The necessary warning: nothing you produce will ever be perfect in your eyes, no matter how much time you spend on it. So be able to let it go, to get to the next feature, even knowing that ‘it could be done better’. It always can.

“Reread, rewrite, reread, rewrite. If it still doesn’t work, throw it away. It’s a nice feeling, and you don’t want to be cluttered with the corpses of poems and stories which have everything in them except the life they need.” – Helen Dunmore

That is our “perseverare diabolicum”. I’m a proponent of refactor and a believer in the capacity to improve on less-than-stellar design. But in some situations, after hitting wall after wall, it is something better to recognize that the direction is hopeless, throw the whole thing out and start back with a clearer mind. Preferably the next morning.

“Editing is everything. Cut until you can cut no more. “ Esther Freud

If this does not sounds familiar, maybe this version will: “We believe in simplicity that is maximizing the code not to write” (Agile manifesto). Once the code does what it needs to do, try to prune it as much as you can. Not especially throwing parts away, but removing them from the core feature when they do not belong there. You do not want to build on cruft.

Improve

“Increase your word power. Words are the raw material of our craft. The greater your vocabulary the more ­effective your writing.” – PD James

This is an impressive one, and I’ve kept it for the end. We’re writing code. The language is our primary material: its words and idioms. Then we have the various structures and patterns, and progressively a whole ecosystem. Getting to know it better opens doors in your mind and in your code.

Conclusion

I hope this short walk in the writing world will give you some ideas for your next coding session. And you, what are your coding practices? Where do they come from?

from:http://blog.8thcolor.com/2012/11/on-writing-code/