Programmers are often advised to write comments in the code about the intent, what they wanted the code to do, rather than about what the code does.
When you think about it, it makes sense. The code already does what it does, no need to write about that. However, what is the code supposed to do is often unclear, especially when the code is buggy.
This is kind of similar to the yeast example above. The rule is to explain why not how.
To give another example, I am trying to learn statistical mechanics. Not to memorize it but to actually grok it. And it turns out that staring at the equations doesn’t help much. I am planning to look into its history to understand what kinds of problems were fathers of thermodynamics trying to solve (something to do with steam engines, I guess) to understand why that specific kind of thinking about the topic is useful.
This quote is correct for many reasons, one of which is that all a computer has to do with a program is execute it; whereas it often falls to humans to modify it, because to us, humans, there exists the concept of “what this program should, ideally, do”. The reason (or, if you like, a reason—though the major one, I would say) why code ought to be clear and readable is in order that humans may be able to (a) evaluate it on the basis of how far the actual program is from what we’d like it to be, and (b) modify the program in order to bring it more into line with the ideal.
This, in turn, gives us a way to respond to the occasional claim that it is not, in fact, necessary that code be human-readable. Clearly, code should be human-readable if there will ever be a case when either (a) humans need to examine it by hand (as opposed to examining it with some automated tools), or (b) humans need to modify it. If this is simply not going to happen (e.g., Java bytecode), then readability is irrelevant.
And now we can apply a similar principle to the ideas in the OP. It is, indeed, important to understand the “how” and the “why” of certain things with which we may, personally, as amateurs (as opposed to domain experts working in the context of commercial/industrial processes), productively interact.
But not otherwise. Someone with whom I was discussing this brought up the following example: suppose you watch a fascinating and enlightening video that tells you all about how jelly beans are manufactured. Having watched it, you can now… produce jelly beans in batches of hundreds of thousands at a time, with the aid of a fully-staffed manufacturing facility, a global supply chain, and industrial-scale equipment that costs millions of dollars?
This is useless knowledge. It is entertainment, nothing more. At worst, it may be insight porn, deceiving us into the sense that we’ve gained some practical understanding of the world, while in fact teaching us nothing that we can actually use.
Programmers are often advised to write comments in the code about the intent, what they wanted the code to do, rather than about what the code does.
When you think about it, it makes sense. The code already does what it does, no need to write about that. However, what is the code supposed to do is often unclear, especially when the code is buggy.
This is kind of similar to the yeast example above. The rule is to explain why not how.
To give another example, I am trying to learn statistical mechanics. Not to memorize it but to actually grok it. And it turns out that staring at the equations doesn’t help much. I am planning to look into its history to understand what kinds of problems were fathers of thermodynamics trying to solve (something to do with steam engines, I guess) to understand why that specific kind of thinking about the topic is useful.
— Harold Abelson and Gerald Jay Sussman, Structure and Interpretation of Computer Programs
This quote is correct for many reasons, one of which is that all a computer has to do with a program is execute it; whereas it often falls to humans to modify it, because to us, humans, there exists the concept of “what this program should, ideally, do”. The reason (or, if you like, a reason—though the major one, I would say) why code ought to be clear and readable is in order that humans may be able to (a) evaluate it on the basis of how far the actual program is from what we’d like it to be, and (b) modify the program in order to bring it more into line with the ideal.
This, in turn, gives us a way to respond to the occasional claim that it is not, in fact, necessary that code be human-readable. Clearly, code should be human-readable if there will ever be a case when either (a) humans need to examine it by hand (as opposed to examining it with some automated tools), or (b) humans need to modify it. If this is simply not going to happen (e.g., Java bytecode), then readability is irrelevant.
And now we can apply a similar principle to the ideas in the OP. It is, indeed, important to understand the “how” and the “why” of certain things with which we may, personally, as amateurs (as opposed to domain experts working in the context of commercial/industrial processes), productively interact.
But not otherwise. Someone with whom I was discussing this brought up the following example: suppose you watch a fascinating and enlightening video that tells you all about how jelly beans are manufactured. Having watched it, you can now… produce jelly beans in batches of hundreds of thousands at a time, with the aid of a fully-staffed manufacturing facility, a global supply chain, and industrial-scale equipment that costs millions of dollars?
This is useless knowledge. It is entertainment, nothing more. At worst, it may be insight porn, deceiving us into the sense that we’ve gained some practical understanding of the world, while in fact teaching us nothing that we can actually use.