8 ms·

There are so many similarities between writing code and writing English. - Thinking of paragraphs as functions with one purpose - keeping sentences short to r

by hbt 11y ago

There are so many similarities between writing code and writing English. - Thinking of paragraphs as functions with one purpose - keeping sentences short to reduce load on working memory and increase comprehension - create visual breaks to help the reader by grouping common stuff together as mini-functions - reduce intimidation factor of reading by removing convoluted stuff - remove cognitive noise (dead code, unnecessary comments, variables declared out of context or too soon etc.) - keeping terminology consistent across the code (domain language) - not using double negatives e.g a = !notLocked - using automated systems to simplify expressions (e.g weird boolean conditions http://www.wolframalpha.com/input/?i=a+%26%26+b+||+c http://www.wolframalpha.com/input/?i=a+%26%26+b+||+c ) etc. Unlike English, it is less difficult to have a program reorganize your code to make it more readable based on a set of cognitive principles. But, beyond the readability and understanding of a function, we should also learn from other engineering fields. For example, system thinking helps tremendously in organizing code if the cost of refactoring code wasn't so risky in dynamic languages.

wpietri 11y ago
And I'd say that the most important similarity is that good code and good prose can't be written in vacuum. "Any fool can write code that a computer can understand. Good programmers write code that humans can understand." - Martin Fowler Anybody who has written a book knows the feeling of slowly going crazy because you lose touch with how readers will take it. People writing long works in English have a host of tricks to overcome this. First, they'll have editors. Generally, they have more than one. They'll have sample readers, often quite a number of them. And then they iterate, going over something repeatedly to make it more readable. Writers I know will spend 2-3x the time in the revision process than they did in writing the first draft. For me, the best way to get that same feedback is pair programming. I was recently looking back at a code base produced by a small team I was on a few years back; the 4 of us did it with pair programming and frequent pair rotation. It is a great code base, one I'm entirely proud of. Clear, readable, well factored, intellectually coherent, and with amazing unit testing coverage. I think that's because every line, every change had two pairs of eyes on it, which meant that we were constantly evaluating readability, constantly testing and reducing cognitive load.
travjones 11y ago
I agree. I find myself making this comparison often. But, I would add a slight caveat to your point because writing takes many forms. For example, the comment I'm writing at this moment does not feel cognitively taxing (loosely speaking). However, writing a manuscript for publication feels very similar to writing code, at least to me. All of this is to say that I think technical writing is similar to writing code.
coroutines 11y ago
Great. Now my English has improved but my coding hasn't. Stop drawing parallels you aren't helping anybody! :D
strommen 11y ago
Based on your list of how you like to write English, I agree. But I think your list is way off-base when it comes to human languages. The beauty of human language is that it allows us to express our individuality as humans. There are an infinite number of ways to write the same thing, and each author can have a unique style based on how they choose their words, structure their sentences, etc. This is fantastic, and is truly one of the pillars of a free society. Consider "Newspeak" in Orwell's 1984 - its entire purpose was to eliminate free thought by eliminating choices in writing and speech. Now in computer programming, I think unique styles are to be strictly avoided. A Newspeak-ish programming language that minimized the ability to write "creatively" would actually be pretty nice.
- glhaynes 11y ago
  Wouldn't want a novelist to strictly follow that list, but I wouldn't mind a technical writer doing so.
  - SpaceCadetJones 11y ago
    Yes, with technical writing I (generally) just want the author to help me get the information into my mind with minimal cognitive effort. There are times where being poetic can help, such as selling me on a new programming model, but most technical writing out there is too long winded for my taste.
- saulrh 11y ago
  Different guidelines for different writing. I will readily agree that this list would result in awful poetry, but then again, uniqueness and individuality would result in equally awful technical writing. So it's not that this list is off-base for human languages. Rather, it's off-base for art.
sametmax 11y ago
Refactoring is not more risky in dynamic languages if you have unit tests to back you up. On the other end, on static language you will likely end up finding out that your initial architecture did not take in consideration this use case or this API, and you may spend a considerable amount of time fixing what would be trivial to do a dynamic language.
eikenberry 11y ago
Also remember that the optimal width for text readability is around 4 inches, or 60 characters. So unless you have many levels of indention, stick to the 80 column rule.
ergothus 11y ago
I agree with everything you said. As an old Perl guy, I found it hilarious that Perl has a reputation for illegibility, while I find it easier to read than most Java, because in Perl I can express my intent, and in Java it's buried in the noise. One cognitive problem I've not yet found a good solution to: So I have a high level routine to, say, sort the items in a display. Said sorting has some cascading effects, so I'll have a high level function that calls some mid level functions that call some lower level functions. But at some point I get a name clash between a high level function and a low level one. Like...I'm calling the high level sortDisplayedItems, (or sort_displayed_items) and there's a low level function that ACTUALLY sorts them (as opposed to handling the other bits). Sure, I can give it a distinct name (e.g. sort_items), but when skimming the code, it's unclear which is which. If I have to mentally parse the code to understand what is happening, I've failed at readability/maintainability. How have others handled this?
- gknoy 11y ago
  > I'm calling the high level sortDisplayedItems, (or sort_displayed_items) and there's a low level function that ACTUALLY sorts them (as opposed to handling the other bits). You're absolutely right: naming things is hard. When I was writing Scheme long ago [in university], our convention was to name helper functions with `-helper` in the name: sort-foos sort-foos-helper sort-foos-merge-helper Now that I write mainly in Python, the convention seems to be to use underscores to indicate things that you should ignore. Usually that's done at a method level, where your consumers are calling the object's public API (sort), so the object's namespace helps reduce such name collisions. The addition of triple-quote docstrings for method comments helps a lot at clarifying purpose as well: class FooSorter(object): def sort(self, foos): """Sort an iterable of Foo objects""" # ... sanity-check inputs ... self._sort(foos) # do the sort operation def _sort(self, foos): """ Sort things we already know are Foo objects. This is a helper for sort(), which already sanity-checked our inputs. """ # do the actual sorting
- deleted 11y ago
  [deleted]
- 11y ago

by hbt 11y ago

wpietri 11y ago

And I'd say that the most important similarity is that good code and good prose can't be written in vacuum. "Any fool can write code that a computer can understand. Good programmers write code that humans can understand." - Martin Fowler Anybody who has written a book knows the feeling of slowly going crazy because you lose touch with how readers will take it. People writing long works in English have a host of tricks to overcome this. First, they'll have editors. Generally, they have more than one. They'll have sample readers, often quite a number of them. And then they iterate, going over something repeatedly to make it more readable. Writers I know will spend 2-3x the time in the revision process than they did in writing the first draft. For me, the best way to get that same feedback is pair programming. I was recently looking back at a code base produced by a small team I was on a few years back; the 4 of us did it with pair programming and frequent pair rotation. It is a great code base, one I'm entirely proud of. Clear, readable, well factored, intellectually coherent, and with amazing unit testing coverage. I think that's because every line, every change had two pairs of eyes on it, which meant that we were constantly evaluating readability, constantly testing and reducing cognitive load.

travjones 11y ago

I agree. I find myself making this comparison often. But, I would add a slight caveat to your point because writing takes many forms. For example, the comment I'm writing at this moment does not feel cognitively taxing (loosely speaking). However, writing a manuscript for publication feels very similar to writing code, at least to me. All of this is to say that I think technical writing is similar to writing code.

coroutines 11y ago

Great. Now my English has improved but my coding hasn't. Stop drawing parallels you aren't helping anybody! :D

strommen 11y ago

Based on your list of how you like to write English, I agree. But I think your list is way off-base when it comes to human languages. The beauty of human language is that it allows us to express our individuality as humans. There are an infinite number of ways to write the same thing, and each author can have a unique style based on how they choose their words, structure their sentences, etc. This is fantastic, and is truly one of the pillars of a free society. Consider "Newspeak" in Orwell's 1984 - its entire purpose was to eliminate free thought by eliminating choices in writing and speech. Now in computer programming, I think unique styles are to be strictly avoided. A Newspeak-ish programming language that minimized the ability to write "creatively" would actually be pretty nice.

glhaynes 11y ago
Wouldn't want a novelist to strictly follow that list, but I wouldn't mind a technical writer doing so.
- SpaceCadetJones 11y ago
  Yes, with technical writing I (generally) just want the author to help me get the information into my mind with minimal cognitive effort. There are times where being poetic can help, such as selling me on a new programming model, but most technical writing out there is too long winded for my taste.
saulrh 11y ago
Different guidelines for different writing. I will readily agree that this list would result in awful poetry, but then again, uniqueness and individuality would result in equally awful technical writing. So it's not that this list is off-base for human languages. Rather, it's off-base for art.

sametmax 11y ago

Refactoring is not more risky in dynamic languages if you have unit tests to back you up. On the other end, on static language you will likely end up finding out that your initial architecture did not take in consideration this use case or this API, and you may spend a considerable amount of time fixing what would be trivial to do a dynamic language.

eikenberry 11y ago

Also remember that the optimal width for text readability is around 4 inches, or 60 characters. So unless you have many levels of indention, stick to the 80 column rule.

ergothus 11y ago

I agree with everything you said. As an old Perl guy, I found it hilarious that Perl has a reputation for illegibility, while I find it easier to read than most Java, because in Perl I can express my intent, and in Java it's buried in the noise. One cognitive problem I've not yet found a good solution to: So I have a high level routine to, say, sort the items in a display. Said sorting has some cascading effects, so I'll have a high level function that calls some mid level functions that call some lower level functions. But at some point I get a name clash between a high level function and a low level one. Like...I'm calling the high level sortDisplayedItems, (or sort_displayed_items) and there's a low level function that ACTUALLY sorts them (as opposed to handling the other bits). Sure, I can give it a distinct name (e.g. sort_items), but when skimming the code, it's unclear which is which. If I have to mentally parse the code to understand what is happening, I've failed at readability/maintainability. How have others handled this?

gknoy 11y ago
> I'm calling the high level sortDisplayedItems, (or sort_displayed_items) and there's a low level function that ACTUALLY sorts them (as opposed to handling the other bits). You're absolutely right: naming things is hard. When I was writing Scheme long ago [in university], our convention was to name helper functions with `-helper` in the name: sort-foos sort-foos-helper sort-foos-merge-helper Now that I write mainly in Python, the convention seems to be to use underscores to indicate things that you should ignore. Usually that's done at a method level, where your consumers are calling the object's public API (sort), so the object's namespace helps reduce such name collisions. The addition of triple-quote docstrings for method comments helps a lot at clarifying purpose as well: class FooSorter(object): def sort(self, foos): """Sort an iterable of Foo objects""" # ... sanity-check inputs ... self._sort(foos) # do the sort operation def _sort(self, foos): """ Sort things we already know are Foo objects. This is a helper for sort(), which already sanity-checked our inputs. """ # do the actual sorting
deleted 11y ago
[deleted]
11y ago