Comparing writing specifications to writing code


My colleague who manages to pack his entire office into a single box recently made the switch from program management to programming. I teased him, "So what's it like using an editor without a 'boldface' button?" His response was actually rather insightful.

"Writing specifications is like writing a novel. Writing code is like writing poetry."

When you're writing a specification, you need to start by setting the scene so people understand the problem you're trying to solve. You then explore the world you've created, elaborating on the details necessary to convey your intent, considering all the possibilities and addressing each one.

When you're writing code, you are focused on conciseness. Like a poet, you are thrilled when you find a single expression that covers all the nuances you're trying to convey. You are intent on writing only what is necessary, no more. Beauty is in the small.

I guess this explains why I was never good at long-form writing.

Comments (35)
  1. Skrud says:

    Ironically, I read this post while in a Software Engineering class just as my prof was saying "Usually you will not be writing code, 90% of your work will go into design, specifications and planning. You will find other people to write code, the same way building and civil engineers get construction workers to move the heavy cement blocks."

    Mind you - I believe that one cannot be a competent software designer/architect/buzzword without first being a code poet. I also prefer code writing.

  2. aidan_walsh says:

    Can we see some Raymond Chen original poetry? =D

  3. Steve Boyko says:

    "Like a poet, you are thrilled when you find a single expression that covers all the nuances you're trying to convey"

    I agree with this in general.  But if this were totally true, APL would have caught on.

    Of course, Perl is (was) the Next Big Thing and with it you can cram a lot of nuance into a single expression.

  4. But how many poets base their work on novels?  

  5. Michael B says:

    Maybe your friend was insulting programmers.

    I'm reminded of a quotation attributed to Paul Dirac, founder of quantum mechanics:

    Or alternatively, when Oppenheimer was working at Göttingen, Dirac supposedly came to him one day and said: "Oppenheimer, they tell me you are writing poetry. I do not see how a man can work on the frontiers of physics and write poetry at the same time. They are in opposition. In science you want to say something that nobody knew before, in words which everyone can understand. In poetry you are bound to say…something that everybody knows already in words that nobody can understand."

  6. James Higgs says:

    Surely the very greatest prose exhibits the same concision? Just because a book is 1000 pages long doesn't mean it could have been shorter to the same effect.

    Milan Kundera says something to the effect that a novel is not a novel if it is tolerable to change one word in it. He's fond of extreme statments like this, but I see his point. Somewhere else, he said that it's immoral to write a novel that tells us nothing new. By that standard, there must be a few immoral specs lying around the place!

  7. A Tykhyy says:

    Michael B: oh please. Euclides (if my memory serves me right) reportedly said of one of his ex-pupils: "he was not talented enough for mathematics, so he became a poet".

    Skrud: I think this analogy is not quite sound. The compiler is the construction crew, moving blocks and pouring cement; the coder is at least the foreman, or even the low-level civil engineer. The ones who write specs should be architects and high-level engineers.

  8. Abc says:

    "I think this analogy is not quite sound. The compiler is the construction crew, moving blocks and pouring cement; the coder is at least the foreman, or even the low-level civil engineer. The ones who write specs should be architects and high-level engineers."

    No, no, no.  The building is the solution to the user's problem.  The construction crew is the software putting together the solution.  The architect producing the blueprints for the construction crew is the programmer.  The city officials granting zoning rights are the spec writers.

  9. Markus says:

    There is a problem with conciseness in that the most concise formulation is often hard to understand (quite like poetry). After all, the most concise programming language known to man is probably Forth ;-)

  10. Mr. Ed says:

    I think coding is like writing newspaper articles.  We're always printing corrections on page 26B.

  11. Diego says:

    Maybe you are agreeing with Linus Torvalds in this? ;)

    (see http://kerneltrap.org/node/5725)

  12. Alyosha` says:

    I'd argue that writing specs like they were novels is a poor way to write specs.  Conciseness is essential to any programming, regardless if it's in English or it's in C++.

  13. Re: "I agree with seeing art in design and engineering, whether mechnical, electrical or software."

    I view software development as a craft, such as blacksmithy or carpentry. There's only room for artistic expression if the requirements and met and the art doesn't interfere with the function of the creation.

    For a while, my resume listed my profession as "Software Craftsman."

    PMP

  14. ionelpop says:

    Do you know these black t-shirts from MSDNAA ? On the front, there is written „Code is poetry“. I like...

  15. Dawn-Marie says:

    Speaking as both a poet and a former CS student (I'm a programmer/writer), I think that the poetry analogy is apt.  Poetry is about communicating precisely, and as efficiently as possible.  Same with coding.  

    But then, in college, the CS students didn't get me because I wrote poetry, and the writers didn't get me because I coded.  They didn't think the two were anywhere near each other.

  16. Dazhel says:

    Paul M. Parks said:

    "For a while, my resume listed my profession as 'Software Craftsman.'"

    Is there any particular reason why it doesn't list it that way now?

  17. dan.g. says:

    i was never any good at writing long essays either. glad to see i'm in good company. :)

  18. :: Wendy :: says:

    The analogy worries me.  Surely writing a Spec is like writting multiple Poems on different yet highly related topics (known usage problems,  feature goals etc).  A themed poety-book perhaps.  Writing code for is analogous.  The themes being drawn from are just different - a slightly different reference scope.

  19. If anyone wants to write about "taking an analogy too far and/or too seriously", they can link to the comments on this post. ;-)  (Or to the CCIA's "monoculture" diatribe from a few years ago!)

  20. Anonymous Coward says:

    I agree with seeing art in design and engineering, whether mechnical, electrical or software.

    What I *disagree* strongly with is people who hide poor software practices behind the "art" description.

  21. no says:

    poetry is about writing something simple in a complicated (and often annoying) way.

    programming is not like that at all.

    it's an awful awful comparison :(

    and as someone else said; compressing "all the nuances you're trying to convey" into a single statement is not really a good thing in most programming languages.

  22. A Tykhyy says:

    no: have you read T.S.Eliot? if so, please tell me what is the simple thing he writes, because I don't get it...

    About compressing nuances: it depends on how you do this. If the statement is full of ?: and one needs half an hour thought to understand what it does, it's probably better to spell it out in several statements. But if you compressed an ugly block of code into a single clear statement which one understands the moment one sees it, it's a genuine success. That's what Raymond meant, I guess.

  23. Richard says:

    > I agree with this in general.  But if this were totally true, APL would have caught on.

    > Of course, Perl is (was) the Next Big Thing and with it you can cram a lot of nuance into a single expression.

    Well at least you can write poetry in Perl. http://www.perlmonks.org/index.pl?node=Perl%20Poetry

    The key being that it does run...

  24. Stu says:

    Thats interesting, because I enjoy writing prose and am rubbish at writing poetry, yet im a coder...

  25. Is coding about self-expression?

  26. Amotif says:

    Cherry blossoms sleep

    Strewn across the garden bed

    Much like my designs

  27. Isaac Lin says:

    Writing poetry isn't actually about finding an expression that expresses that covers all you want to convey, or at least so I was taught. It is about finding words whose sound reinforce the message, or is in fact the message itself.

  28. Jules says:

    Sorry, I think your colleague's totally wrong.  Novels are much more similar to coding than poetry is, both in terms of average project length (an average novel contains about 100,000 words which would equate to about the same information as 10,000 lines of code I guess) and the conciseness of the statements you write.  Also, most novelists write with an outline, which is a good analogue to a formal spec ... and in both fields there are people who prefer to wing it without one.

  29. Nawak says:

    I don't like the comparison either.

    When I write code, I aim (but not always succeed as I'm still young) to write *maintainable* code, and often I have to explain things, both in code and in comments.

    I think that poetry is too personal to be compared with code, I want my code to be more 'universal' to understand. I want think about the poor guy whose brain is not like mine, and often it also means I think about myself in two years.

    But I agree that when you find a simple statement that does everything you want, while still being understandable by anybody who can 'read', it IS satisfying and beautiful.

  30. James willson says:

    May be yes..writing code is like writing poetry but imagine the effort is takes to understand the peotry and trying to run a sustenance program on it

  31. Norman Diamond says:

    Thursday, February 09, 2006 3:08 PM by Nawak

    > to write *maintainable* code

    Oh yeah.  Think of the poor workers two years later who get assigned to add features to your poetry.

Comments are closed.

Skip to main content