Writing contracts and prose

04 Feb 16

Software coder Eric Suh writes, in a piece entitled, Writing code and prose:

One of the most important qualities for effective programming in large codebases is good writing ability—not writing code, but writing prose for other humans.
Undoubtedly, this is not a surprise to long-time industry veterans (after all, we don't often program in machine code anymore), but it's a quality I often find is overlooked by engineers that arrive straight out of college. Those that I see write the cleanest, most maintainable code are those who write prose well, whether in documentation, in emails, or in their everyday lives.
Many aphorisms about writing style translate fairly well to coding. Consider the following selection of principles from The Elements of Style by Strunk and White:

  • "Place yourself in the background," and "Do not overwrite." The best code does its job honestly and without obscuring its meaning with the author's "style." If code is so obviously stylized, it is probably written poorly. Exploiting all of the obscure bells and whistles of a language makes for brittle, obscure code.
  • "Work from a suitable design." Plan ahead and make deliberate design choices. Choosing the right architecture makes a huge difference in how cleanly or how tortured your code will read.
  • "Revise and rewrite." Or in the words of Fred Brooks in The Mythical Man-Month: "Plan to throw one away." Your first solution will take longer than expected, have problems you didn't foresee, will likely have code put in the wrong places, and have abstractions drawn at the wrong lines. Write a second draft.
  • "Use definite, specific, concrete language." Vague names like lookup_table or callback are useless in much application code. Use more specific, concrete, and informative synonyms like users_by_id or on_success.
  • "Omit needless words." We need not be obscurely terse—we aren't counting characters for source code anymore—but concise, simple code is best. Use abstractions and language features to remove boilerplate and focus on core logic.
  • "Express coordinate ideas in similar form." Similarity in structure emphasizes similarity in idea, allowing readers to pattern match and understand your code more quickly. Beware, however, the limits to foolish consistency.
  • "Keep related words together." Save your reader from having to jump around different files and switch contexts to follow lines of logic. It is tiring and difficult to do, even with the help of an IDE. Use tools like promises, monads, and other abstractions to write code in linear, readable progressions that would otherwise be fragmented.
  • "Prefer the standard to the offbeat." Be idiomatic. Follow the standard styles of a codebase and language community. Don't vary for the sake of variance.

And one more aphorism from journalism that I think applies to programming:

  • Don't bury the lede. Document up front. Put public methods and interfaces at the top of a file, not halfway down past implementation details (when possible). Your code should read like a newspaper article: headline to start, the main gist at the beginning, and then more gristly details further down if the reader is hooked and interested.


Query Thread Page

On this page you can:
  • subscribe to this query
    By subscribing, you will receive email (as frequently as you specify) of new activity in this query.
  • vote up or vote down queries and replies
    Voting is a generalized proxy for your assessment of the worth, quality, articulation, etc of a query or reply. Voting up a reply or query increases the reply/query author's mojo by one. After you vote, you have five minutes to undo it.
  • reply to the query or add a comment to the query or any reply
    A reply is a serious substantive response, worthy of addition to the knowledge being recorded for all of us here. Comments, simply, are for responses that are not replies (questions, clarifications, caveats, etc). You must scroll all the way down to add a reply; might as well read all of the replies on the way down. If you would like to include with your reply new legal text for others to edit, feel free to add a clause. Adding a reply gives you one mojo.
  • edit a clause (quick-reply)
    If you want to quickly add a reply that is an edit of another member's legal text, click the edit clause link on the clause you wish to edit, and you will be taken to the bottom of the page, with the text of the clause ready for your edits.
  • select best reply (if you are the author of the query)
    If you authored this query, be sure to select the reply that you believe is the best (and consider explaining why you selected this reply as best in a comment to that reply). You receive one mojo for doing so. The author of the reply you select as best will receive four mojo or the bounty award you posted for this query. You can change your mind as many times as you want. If you de-select a best reply, the reply author loses two mojo or the bounty mojo awarded, and you lose one mojo.
  • edit/update or delete query (if you are the query author)
    If you authored this query, you may edit it at any time, and delete it before a reply has been posted to it. Clauses may be edited only if no other member has redlined that clause. You may also add a bounty award or increase already-posted bounty, at any time (even after a reply has been posted).
  • flag (ie complain about) a query, reply or comment
    Use as sparingly as appropriate given the circumstances.
  • quiver and favorite
    You may add/remove this query to/from your favorites, and add/remove clauses in this query to/from your quiver. If you are a guild moderator, you can similarly add/remove this query to/from guild favorites, and add/remove clauses here to/from your guild quiver.

A friendly reminder: be excellent to each other and remember the human.

FAQs | How do I ...?
What are subscriptions?
Redline allows you to subscribe to queries (so that you can be alerted to new replies and comments that are posted to those queries), members (so that you can know of new queries posted by that member) and guilds (so that you can track new queries posted with tags of guilds you follow). With subscriptions, you are notified via email, and on the Home (Your Notifications) page, of new activity corresponding to your subscriptions. Via the Settings/Subscriptions page, you can manage your subscriptions, including altering the timing of notification emails.