« « Learning to love…namespacing (advancing code organization)

Passing another milestone… » »

“Is there a Strunk & White for code?”

Posted by on Aug 20, 2012 in Blog | 7 Comments

In my last post, Lisa Williams asks in the comments:

“So is there a Strunk and White for code? I’m teaching myself, and I know things like my indentation and the like must be all screwed up, but I haven’t really found any reference that would help me out. Do the conventions vary widely from language to language?”

The answer, or what I’ve gleaned from my study so far, isn’t simple, so I’m extending this into a blog post.

It seems to me that basic principles remain the same, but how you make them happen is what differs.

Put another way, when we write, we organize our thoughts in sentences, which get grouped into paragraphs. Paragraphs are placed in order, to hopefully form some type of narrative. But if I write a news story in French, it differs from English in that it uses different words and characters. The order of words in sentences even changes: “le chat bleu” as opposed to “the blue cat”. But the principle of sentences, paragraphs and logical flow still apply. And to further push this metaphor, Strunk & White doesn’t go into detail about how to structure paragraphs, but rather what you put in the paragraphs. Same with the majority of coding references I see.

But for what it’s worth, I’m trying to learn the language of JavaScript, for example, as well as how “paragraphs” work in code. Attacking both at once is even more confusing, not to mention the fact that the last time I learned the elementary basics of structuring a document, I started in kindergarten.

Mentors of mine have suggested the books Refactoring: Improving the Design of Existing Code and Code Complete (Amazon links informational only, not meant as telling you to buy it). But frankly, I find them to be quite difficult to wrap my head around, at my current skill level. When I reread five times, I get it. They’re worthwhile, but require careful study.

Since an object {} should contain everything, there are things called JavaScript object patterns, and I imagine similar things for other languages. I’ve tried many links on this, and a favorite is the virtual “book” Learning JavaScript Design Patterns.

But before we get to all that, there are some simpler lessons I’ve taken away, that have helped me “get” it more than the rest of the resources, at least for where I am right now in my coding journey.

  • Outline what you will do first, in pseudocode, that is use English to describe what you will tell the computer to do. Write it like an outline, with sections and subsections.
  • Convert that into functions. Functions call other functions; you should be able to describe every function in a topic sentence. Right now, I like to write that topic sentence at the start of my functions.
  • Order functions following a logical path from specific to general. The inner functions a larger function uses goes directly above it, then we move to the next set of inner functions to larger functions. A giant call to initialize the whole thing goes at the bottom.
  • Write a bunch of comments to remind yourself what’s happening. Reading just the comments, from bottom to top, should read with some sort of narrrative or logical structure.

Lisa also asked about indenting, and I struggle with that too. Again, I think of it like an outline I used to make in school. If something is a part of something else (a function, an HTML element), it goes in a level. This makes it easier to see when you’ve forgotten to close something with a stray } or ). I don’t know that there’s any great resource on that other than practice, and copy editing yourself.

Of course, for me, the healthy fear of having my code reviewed keeps me honest. If I don’t indent correctly, I’ll hear about it. It’s important to have people who can review your stuff, whether inside or outside your organization.

But it’s still a lot of self teaching. In the end, it’s up to me. A quote from a reviewer when I felt guilty for messy code: “Don’t apologize to me. I’m just looking at it once. You’re the one who has to live with it.” Truth.

If anyone out there wants another set of eyes on their stuff, I’m always happy to take a look — I could use the practice. If I don’t know the answer, I’ll ask someone smarter.

Hope that helps, Lisa. That’s as much as I know now, but I’ll post more when I figure more out.

« « Learning to love…namespacing (advancing code organization)

Passing another milestone… » »
  • http://richardcornish.com/ Rich

    JavaScript has a certain looseness in syntax and style that is supposed to encourage beginners to use the language. Its looseness (and even errors in the language itself) can be attributed to its being shipped so quickly during the browser wars of the 1990s. Yahoo!’s Douglas Crockford created JSLint (http://www.jslint.com/) to encourage best practices for indentation and other white space, semicolons, equality operators, global variables, and more. JSLint is a bit of a stickler, and so JSHint (http://www.jshint.com/) might be a helpful alternative, especially if JSLint’s complaints are too hard to figure out.

    - Code conventions for the JavaScript programming language (http://javascript.crockford.com/code.html)

    - A survey of the JavaScript programming language (http://javascript.crockford.com/survey.html)

    - A re-introduction to JavaScript (https://developer.mozilla.org/en-US/docs/JavaScript/A_re-introduction_to_JavaScript)

    - Seven JavaScript things I wish I knew much earlier in my career

    - Immediately-invoked function expression (http://benalman.com/news/2010/11/immediately-invoked-function-expression/)

    Some developers have been known to scoff at Crockford’s suggestions, and because JavaScript’s looseness allows for it, deciding what is and isn’t a good practice has been the cause for many useless flame wars. On this issue, I tend to follow Python’s philosophy that code is more often read than written; therefore, readability trumps cleverness. I think that’s a noble and worthy endeavor alone and absolutely essential when working with a team. You can read these ideas by importing `this` in any Python terminal, known as the Zen of Python. (http://www.python.org/dev/peps/pep-0020/) JavaScript has no such higher ideals, but consistent four-space indentation and explicit semicolon placement alone have made my code much more organized and readable.


    Lisa Williams Reply:

    Thank you so much! This is very useful!


  • http://twitter.com/richiec/status/238016714242158593/ @richiec

    @lisawilliams Posted a response on Michelle’s post for you. You should remove the extra “)” on my links though. http://t.co/vRMHjsCw


  • http://twitter.com/kpark505/status/238279764832555009/ @kpark505

    So many new blog posts from @michelleminkoff! Links from this post on coding conventions are especially helpful to me: http://t.co/mc41EZo4


  • http://borasky-research.net/about-data-journalism-developer-studio-pricing-survey/ M. Edward (Ed) Borasky

    There used to be a “Strunk and White for code”. Every decent-sized programming shop I ever worked in had a style guide and conventions for programming teams. That’s somewhat fallen by the wayside; teams tend to be smaller now than they used to be so there’s less need for that. But you can bet on a big project, like Linux, R and Perl, there very much are “style guides”


    Rich Reply:

    That reminds me of GitHub’s style guide. https://github.com/styleguide

    I think there could be some misinterpretation to what end a programming style guide is beneficial. Unlike a style guide meant for words read by the public, where it’s essential people receive a predictable reading experience, internally only the team members need be on the same page. In that respect, there is nothing wrong with writing JavaScript how you want as long as everybody on the team is consistent.


    M. Edward (Ed) Borasky Reply:

    I’m not a JavaScript programmer, but I have read “Javascript: The Good Parts” and “Secrets of the JavaScript Ninja”. A predictable reading experience is *more* important in code than in English. There’s a lot more redundancy and context in English than there is in code.