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.
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.
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.