This is an interesting read. The structured approach to writing (code or prose) with intent is surprisingly rare among developers of various skill levels in my experience.<p>One of the key pieces of advice I give to new recruits is "write a paragraph about your intent, what do you want this code to do?". This, it turns out, is non-intuitive for folks as it requires first understanding what is there (OP notes this well) before jumping into coding. I think the root of this is that you're paid to write code and you want to impress right from the start.<p>Thus I found it very interesting when a few Q4's ago I was tasked with creating a new recruiting site for engineers ( <a href="https://engineering.twitch.tv" rel="nofollow">https://engineering.twitch.tv</a> ) to better understand our culture. The central focus of this site was to be a series of blog posts which highlighted core work that had recently taken place. My job quickly became editor in chief; working with engineers of various levels to understand what they've been doing, what was cool about it, and get them writing about it. Seven blog posts were identified and I made calendar events to check in seven days from then to read drafts... seven days later no drafts existed. As I dug into this it was apparent that they'd all assumed they could jump into the writing prose much like they do code, they all remarked that writing prose is actually really hard. I provided a template of my own pieces over the years and by the following quarter we had three pieces written!<p>I credit TPW for giving me words to describe this to engineers ( <a href="http://tom.preston-werner.com/2010/08/23/readme-driven-development.html" rel="nofollow">http://tom.preston-werner.com/2010/08/23/readme-driven-devel...</a> ) and my high school English teachers for giving me the love of words!
I think the more useful side to this is that the path to understanding a codebase or library is in some ways like understanding a literary work.<p>It takes some time, rereading a bit. discussing it with other people who are reading it, making the right amount of notes in the margin, consulting the dictionary when you don't understand a term. If it's in a language you don't know, you can translate it slowly, but knowing the basics goes a long way.<p>I like this way of looking at it because it has more to do with gaining understanding than with promoting some semantic style in regards to documenting
I studied both English and CS in a hybrid program in college. One of the things that appealed to me about writing great code is that it did parallel good writing. The process of writing, especially a paper or a longer thesis relies on logic. There have to be clear bridges, or segues between sometimes disparate thoughts, connecting them.<p>I find when I am writing code, I try to use the same principles. I don't want anyone to look at two isolated pieces of code and think "what the hell, these don't even belong in the same universe, let alone the in same repo." Whether through comments or just good self-documenting code, I want things to connect in some way.<p>Jeremy Ashkenas made the connection in a piece of his writing about coffeescript as well. Kind of an ah-ha moment for me.
I agree that one should strive to make good code human-readable and I often also try to use names in a grammatically correct way (to make reading easier).<p>However, this article leaves me wishing he'd show examples of what he's talking about.<p>I'd like to see his code to determine whether it <i>reads</i> more prose-like.
Really any creative task is the same: writing music, writing software, writing prose.<p>You have your primitive ideas for some chosen rules, chosen such that the desired product is a valid idea in those rules. Then you combine your ideas through concatenation and composition to get more complex ideas. Sometimes you realize your rules aren't quite right so you change them some. You keep doing this until you have a big idea that fits your definition of a "solution" (whatever that means) and then you're done.
Editors really need to improve their support or comments. Currently, they're even deemphasised in some color schemes (looking at you VSCode).<p>I built a prototype for an Atom extension a while back that rendered Comment blocks with a markdown parser, inline, right in the editor.<p>I'm hoping that the VSCode team gets around to implementing the extension hooks necessary to implement this at some point, since I've switched away from Atom.
A code comment is not like an intro paragraph. Comments are second class compared to code; see any code base. Of course they don't actually do anything except confuse humans, partially because they have no defined syntax or grammar, and partially because most programmers fail to maintain them as they change code.
Don't really understand this article. It just takes the writing process and inserts bits about writing good code into it. If anything, good code should read like Hemmingway and nothing else. And as such, not all good prose will be as dry and concise.
Whether you use it or not the Illumos code base[1] is one of the most well written I've seen in this respect.<p>[1]<a href="https://github.com/illumos/illumos-gate" rel="nofollow">https://github.com/illumos/illumos-gate</a>
I can see some merit in this, a story will often reveal the problem better than cold analytics, but I have to say I still think the common approach of defining the objects and then the actors is going to get a better outcome.