{"id":12,"date":"2019-04-19T05:53:00","date_gmt":"2019-04-19T05:53:00","guid":{"rendered":"https:\/\/alphaloop.co.uk\/blog\/?p=12"},"modified":"2020-07-19T19:39:28","modified_gmt":"2020-07-19T19:39:28","slug":"prose-before-codez","status":"publish","type":"post","link":"https:\/\/alphaloop.co.uk\/blog\/posts\/12","title":{"rendered":"Prose Before Codez"},"content":{"rendered":"\n

Ernest Hemmingway once said that writing is easy: all you have to do is sit at a typewriter and bleed. The same could be said of coding, although you really need a computer rather than a typewriter. Writing code on a typewriter is a very long-winded way of going about developing software, and isn\u2019t generally recommended unless you\u2019re some kind of super-committed hipster with an bespoke typewriter and an artisanal hair clip to keep your epic beard from getting caught in the hammers.<\/p>\n\n\n\n

\"Image
iStock.com\/doomu<\/figcaption><\/figure>\n\n\n\n

I like writing, and I like writing code. I especially like writing code that kind of reads like writing, but I try and avoid the opposite, because it\u2019s very frustrating and ultimately pointless, like region encoding and DRM.<\/p>\n\n\n\n

I\u2019ve been thinking for a while about the similarities and differences between writing and writing code, and I thought it might make an interesting post. Fortunately, as previously stated, I like writing, so here it is.<\/p>\n\n\n\n

Know Your Audience<\/h2>\n\n\n\n

\u201cThe best audience is intelligent, well educated and a little drunk.\u201d <\/p>Alben W Barkley<\/em><\/cite><\/blockquote>\n\n\n\n

It\u2019s well-established that when writing, you should keep your audience in mind. Who are they? Why will they be reading this? What will they be hoping to get out of it? What knowledge can you assume? How easily offended might they be? Is this really the right forum for that dick joke?<\/p>\n\n\n\n

The hardest part about writing code<\/em> is that you\u2019re writing something that necessarily has to be consumed by two completely different audiences at the same time: the machine, and other programmers. The machine is precise, unwavering, pedantic, and utterly refuses to help you out by looking past the specifics of what you said to what you obviously mean, whereas programmers\u2026 well maybe the two audiences aren\u2019t completely different, but nevertheless.<\/p>\n\n\n\n

Writing good code is the art of giving the machine precise instructions in a highly constrained language while at the same time clearly conveying your intent to a human reader. Most bugs live in the gap between what the programmer intended and what they actually wrote, so it\u2019s really helpful if you can express that intent as part of the code. The downside is that this can feel like a lot of extra work at the time, and it means that you don\u2019t get to name your variables fun things like \u201cfoobar\u201d, \u201cl33Tsk1lZ\u201d or \u201cbumsex\u201d\u2020.<\/p>\n\n\n\n

However, even if you hate your fellow programmers or work alone, the next person to come along and read your code might be a future instance of yourself, and they\u2019re going to be really pissed off if you make life hard for them: about as annoyed as they are when you set the alarm the night before so they can get up early and exercise.<\/p>\n\n\n\n

Don\u2019t Make Me Think<\/h2>\n\n\n\n

\u201cThinking is the hardest work there is, which is probably the reason why so few engage in it.\u201d <\/p>Henry Ford<\/em><\/cite><\/blockquote>\n\n\n\n

Understanding code is hard work, especially code you\u2019ve not written yourself. Even modern programming languages are heavily constrained in terms of how expressive they are for the human reader, so part of your job as a programmer is to make it as easy as possible for someone else to understand what the merry hell they\u2019re looking at.<\/p>\n\n\n\n

There are a lot of techniques you can apply here, but the main thing to bear in mind is that you\u2019re trying to reduce the cognitive load on the reader. It might take longer for you to think of and type a precise, descriptive variable name, or to break a function out into several smaller pieces, but your team will recoup all that in time not spent furrowing their brows and cursing you under their breath.<\/p>\n\n\n\n

The same is true in writing. If you read what you\u2019ve just written and find yourself stumbling over a sentence, something needs to change. Maybe you need to put a hyphen between two words to clarify something which would otherwise be ambiguous, or maybe you need to reverse the whole sentence because the context at the end would help the reader interpret the point you made at the beginning. Again, all the extra effort you put into crafting and polishing the text makes it easier to absorb, allowing people to focus on what you\u2019re trying to say instead of stumbling over how you\u2019ve said it.<\/p>\n\n\n\n

Less is More<\/h2>\n\n\n\n

\u201cA smaller quantity may, counter-intuitively, prove to have greater impact than if there had been more of whatever it was that there was, in fact, less of.\u201d <\/p>Ludwig Mies van der Rohe (early draft)<\/em><\/cite><\/blockquote>\n\n\n\n

When writing, you should aim to express yourself as succinctly and simply as possible. No one will thank you for making them read something that didn\u2019t add any value, just as no one will thank you for making them read code that\u2019s duplicated or unused.<\/p>\n\n\n\n

That is all.<\/p>\n\n\n\n

Read<\/h2>\n\n\n\n

\u201cI\u2019m one of the few people who\u2019s written more books than I\u2019ve read.\u201d <\/p>Garth Marenghi<\/em><\/cite><\/blockquote>\n\n\n\n

It would be ill-advised for someone to attempt to write anything of much importance if they hadn\u2019t read that much, but I\u2019m pretty sure when I graduated with my Computer Science degree back in the heady days of 2001 that I really had<\/em> written more code that I\u2019d read. That\u2019s preposterous. You learn to write well by reading good writing: you learn to code well by reading good code.<\/p>\n\n\n\n

Step Away from the Keyboard<\/h2>\n\n\n\n

\u201cYou\u2019re not paid to think! A mindless worker is a happy worker!\u201d <\/p>Professor Farnsworth<\/em><\/cite><\/blockquote>\n\n\n\n

When writing or coding, most of the really important work happens before your hands touch the keyboard.<\/p>\n\n\n\n

There\u2019s no point in sitting down and trying to write something if you\u2019ve given it little prior thought. Sure, there comes a point when you need to actually start typing in order to thrash out the details, but you need some sense of where you\u2019re headed before you start, and it\u2019s easier to work that out if you\u2019re lying in the bath drinking cheap Merlot than if you\u2019re sitting in front of an uncooperative text editor being badgered by the spell-checker. \u2021<\/p>\n\n\n\n

Likewise, there\u2019s no point in typing frantically into an IDE if you have no idea how your code is going to work. Before you start, you need to understand the problem you\u2019re trying to solve and roughly how you\u2019re going to go about it. At the very least, you need to be able articulate clearly what it is you\u2019re trying to achieve.<\/p>\n\n\n\n

Kill Your Darlings<\/h2>\n\n\n\n

\u201cIn writing, you must kill your darlings.\u201d<\/p>William Faulkner<\/em><\/cite><\/blockquote>\n\n\n\n

Sometimes you can spend a significant portion of time lovingly crafting something, only to find yourself suspecting that what you\u2019ve produced is, in fact, a steaming pile of crap. This is fine: it\u2019s part of the process. It\u2019s not always possible or sensible to try and work out where a line of thinking will take you before you\u2019ve made a start: sometimes the result has to be staring you in the face before you know for sure.<\/p>\n\n\n\n

However, just because you spent a lot of time on something doesn\u2019t mean it\u2019s valuable. Don\u2019t be afraid to delete whole paragraphs that add nothing, and don\u2019t feel bad about putting that beautiful-but-ultimately-useless class to one side and doing a git reset \u2014 hard.<\/p>\n\n\n\n

Don\u2019t Be Clever<\/h2>\n\n\n\n

\u201cIt\u2019s such a fine line between stupid and clever.\u201d <\/p>David St. Hubbins<\/em><\/cite><\/blockquote>\n\n\n\n

If someone has to be a genius to understand what you\u2019re trying to convey, in most cases, you\u2019ve done a bad job. Likewise, if someone needs to be a Linus Torvalds-grade propeller-head to understand your code, in most cases, something\u2019s gone wrong.<\/p>\n\n\n\n

Just because something is clever (an obscure word, or a little-know language feature), that doesn\u2019t necessarily mean it\u2019s a good idea. All else being equal, if there\u2019s a simpler way to do it, do it that way. Your job is to make life easy for everyone else, not to show off.<\/p>\n\n\n\n

Always Write Well<\/h2>\n\n\n\n

\u201cIt\u2019s a funny thing, the more I practice the luckier I get.\u201d<\/p>Arnold Palmer<\/em><\/cite><\/blockquote>\n\n\n\n

One of the best ways to maintain and improve your writing is to always write well, no matter what you\u2019re writing. It doesn\u2019t matter if it\u2019s an email, a comment on a blog post, or a text message: always aim to communicate clearly.<\/p>\n\n\n\n

The same is true when writing code, although if I\u2019m honest I find this more difficult to stick to. Just because this code is part of a unit test, that doesn\u2019t mean it shouldn\u2019t still be readable and clear: in fact it might be even more important.<\/p>\n\n\n\n

Prose Before Codez<\/h2>\n\n\n\n

\u201cWithout requirements or design, programming is the art of adding bugs to an empty text file.\u201d <\/p>Louis Srygley<\/em><\/cite><\/blockquote>\n\n\n\n

How may times have you started to write some code only to realise you didn\u2019t fully understand what it was you were trying to do? Likewise, how many times have you started to explain something you thought you understood to someone else, only for it to slowly dawn on you that there were whole aspects you hadn\u2019t thought about, and now you feel kind of silly.<\/p>\n\n\n\n

The act of putting ideas into words forces you to think clearly and precisely, which isn\u2019t how the human brain works a lot of the time (at least mine doesn\u2019t). We have a lot to think about, so we tend to bleep over things and make lazy assumptions. However, once you\u2019re putting those fuzzy thoughts into words you\u2019re forced to make choices about how to express them, and those choices force you to crystallise the, you know, fuzzy stuff.<\/p>\n\n\n\n

The upshot of this is that it\u2019s often a good idea to write down what it is you\u2019re about to try to do before you start. Do you really know what the requirement is, or are you working off the back of a one-line user story? Can you define the scope and purpose of your system, let alone the change you\u2019re about to make to it?<\/p>\n\n\n\n

Conclusion<\/h2>\n\n\n\n

Conclusion \u2014 noun; a concatenation of \u201cconcussion\u201d and \u201cillusion\u201d. To browbeat a victim until they hallucinate understanding.<\/p><\/blockquote>\n\n\n\n

Writing and coding are both hard to do well, but nevertheless very worthwhile and often overlapping and complementary. No matter how long you do either, there\u2019ll always be room for improvement, and I\u2019m starting to suspect there\u2019s a limit to how well you can do the latter without putting effort into getting better at the former.<\/p>\n\n\n\n

\n\n\n\n

\u2020 This is a real one taken from some code I reviewed quite a while ago. It\u2019s second in it\u2019s inappropriateness only to the name of a test method I wrote while testing a security feature, which in all innocence I decided to call \u201cattemptToDoForbidenThingsOnBackEnd\u201d.<\/p>\n\n\n\n

\u2021 This works for me at any rate: your millage my vary. Also bear in mind that drinking in the bath violates most companies\u2019 open-plan etiquette, so work from home or pick your moment wisely.<\/p>\n","protected":false},"excerpt":{"rendered":"

Ernest Hemmingway once said that writing is easy: all you have to do is sit at a typewriter and bleed. The same could be said of coding, although you really need a computer rather than a typewriter. Writing code on a typewriter is a very long-winded way of going about developing software, and isn\u2019t generally … <\/p>\n

Continue reading “Prose Before Codez”<\/span><\/a><\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"closed","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[7,8],"tags":[3,2,9],"class_list":["post-12","post","type-post","status-publish","format-standard","hentry","category-software-development","category-writing","tag-development","tag-software","tag-writing"],"_links":{"self":[{"href":"https:\/\/alphaloop.co.uk\/blog\/wp-json\/wp\/v2\/posts\/12"}],"collection":[{"href":"https:\/\/alphaloop.co.uk\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/alphaloop.co.uk\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/alphaloop.co.uk\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/alphaloop.co.uk\/blog\/wp-json\/wp\/v2\/comments?post=12"}],"version-history":[{"count":3,"href":"https:\/\/alphaloop.co.uk\/blog\/wp-json\/wp\/v2\/posts\/12\/revisions"}],"predecessor-version":[{"id":22,"href":"https:\/\/alphaloop.co.uk\/blog\/wp-json\/wp\/v2\/posts\/12\/revisions\/22"}],"wp:attachment":[{"href":"https:\/\/alphaloop.co.uk\/blog\/wp-json\/wp\/v2\/media?parent=12"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/alphaloop.co.uk\/blog\/wp-json\/wp\/v2\/categories?post=12"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/alphaloop.co.uk\/blog\/wp-json\/wp\/v2\/tags?post=12"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}