Mastodawn

Discussion between John Ousterhout and Robert Martin ("Uncle Bob"" on "A Philosophy of Software Design" and "Clean Code"

https://feddit.org/post/19744676

Discussion between John Ousterhout and Robert Martin ("Uncle Bob") on "A Philosophy of Software Design" and "Clean Code" - feddit.org

This is a discussion between Ousterhout and Martin, who advocated in “Clean Code” to omit comments and split code in extremely small functions. Ousterhout takes that to town by asking Martin to explain an algorithm which Martin presented in his book on “Clean Code”, and algorithm that generates a list of prime numbers. It turns out that Martin essentially does not understand his own code because of the way it is written - and even introduces a performance regression! It gets even more hilarious when one considers where Martin has taken from the algorithm, and who designed it originally: Martin took it from a 1972 publication of Donald E. Knuths seminal article on Literate Programming: http://www.literateprogramming.com/knuthweb.pdf [http://www.literateprogramming.com/knuthweb.pdf] In this article, Knuth explains that the source code of a program should be ideally understood as a by-product of an explanation which is directed at humans, explaining reasoning, design, invariants and so on. He presents a system which can extract and assemble program source code from such a text. Even more interesting, the algorithm was not invented by Knuth himself. It was published in 1970 by Edsger Dijkstra in his “Notes on Structured Programming” [https://repositories.lib.utexas.edu/items/e7a89f42-dbf6-4929-802d-c75d1cbac378/full] (with a second edition [https://www.informatik.uni-bremen.de/agbkb/lehre/programmiersprachen/artikel/EWD-notes-structured.pdf] in 1972). In this truly fascinating and timeless text, Disjkstra writes on software design by program decomposition, proving properties of program modules by analysis, using invariants to compose larger programs from smaller algorithms and design new data types, and so on. Also, how this makes software maintainable. In this, he uses the prime number generation algorithm as an extended example. He sresses multiple times that both architecture and invariants need to be documented on their on, to make the code understandable. So, Robert Martin is proven wrong here. He does not even understand, and could not properly maintain, the code from his own book. Nor did he understand that his code is hard to understand for others.

Show thread

IanTwenty Oct 4

Another thank you for posting this, made my day.

I have read and followed a fair amount of Uncle Bob’s work but was not aware of Ousterhout till now. Bob says during the time the Clean Code book was written there was an anti-comment sentiment about and this matches my own experience. I agree with Ousterhout that it’s taken too far in his book though.

I wonder if there is another factor at play - some people/cultures prefer high context communication and some less. Bob seems clearly to prefer low context i.e. the burden is on the (code) reader to educate themselves. Whereas John makes it a matter of professional behaviour that we make the next reader’s work as simple as possible by commenting code as appropriate.

Surely it’s better to assume high context is needed and provide it (within reason) versus only catering for low context. As Bob discovered he became a low context person when he returned to his own code after some time had passed.

Show thread

HaraldvonBlauzahn Oct 5

Bob says during the time the Clean Code book was written there was an anti-comment sentiment about and this matches my own experience.

But, with this, doesn’t he weasel out of the responsibility to give clear, logical, verifyable reasons for his position?

Can you explain that more?

And doesn’t the example with the prime number generation algorithm show clearly that omitting context just does not work for code?

Show thread

IanTwenty

doesn’t he weasel out of the responsibility to give clear, logical, verifyable reasons for his position?

Absolutely, if I remember right he leans back on having experienced bad comments more often than helpful ones. John questions this. I think it is close to dogma with Bob on this.

Can you explain that more?

And doesn’t the example with the prime number generation algorithm show clearly that omitting context just does not work for code?

Quote from en.wikipedia.org/…/High-context_and_low-context_c…

High-context cultures often exhibit less-direct verbal and nonverbal communication, utilizing small communication gestures and reading more meaning into these less-direct messages. Low-context cultures do the opposite; direct verbal communication is needed to properly understand a message being communicated…

Now I’m not making a strong claim that Bob and John are from different ends of the context spectrum. However it seems to me that Bob believes there is enough ‘context’ available in code and in coders themselves to communicate all meaning without comments.

Even Bob’s diagram, to help explain the primes algorithm, assumes high context in the reader. It’s lacking any labels or key - we are just supposed to see what he means if we stare hard enough at it. If we are already immersed in the problem space then this might work but its so inefficient for anyone else.

And once we step away from our code for even a short time we are that someone else. We are going to waste a lot of time rediscovering how the algorithm works. A case John makes convincingly I think.

Code cannot replace comments. The primes algorithm avoids division I believe but this is not clear from the code alone. A reader might work this out eventually but a comment saves so much time. Could the code be refactored to clearly express the avoidance of division? Yes there’s probably a way, but imagine how bad that code would read and what a waste of time just to avoid a comment.

Discussion between John Ousterhout and Robert Martin ("Uncle Bob") on "A Philosophy of Software Design" and "Clean Code" - feddit.org

High-context and low-context cultures - Wikipedia