Thanks for sharing this article! I’ve actually been thinking (and writing) a lot lately about communicating intent when coding.
I agree with the author that, when programming, we ought to be mindful of what our code’s audience will need to know and then make sure our code communicates that information. I think that this responsibility flows from the very purpose of code, which is to instruct a computing device what to do in a form that is easy for the code’s intended audience to understand. It follows, then, that good code must communicate three things: (1) what the machine was instructed to do, (2) what we intended the machine to do, and (3) why we wrote the code in the way that we did. Since programming languages offer only limited opportunities to communicate items (2) and (3) by how we structure logic and choose names, good code usually has some comments. That is why I am not a fan of the idea, popular in some circles, that comments are sign of poor craftsmanship.
I agree; comments only highlight the limits of the expressiveness of the programming language. Does this say something about the language's choice of compromise, prioritising neither the computer nor the reader outright? I don't know if it matters how much commentary a language needs to communicate everything that matters. At one extreme, I can easily imagine a language that reads like a research paper, where there could be paragraphs of prose explaining one incredibly dense formula. I don't really know how the other direction would work, if we've even developed the requisite theory yet.
comments only highlight the limits of the expressiveness of the programming language.
I'd argue instead that comments highlight that programs have two simultaneous audiences: the machine and the humans. What is expressive to one audience is not well suited to the other, so programming languages have syntax for both logic and comments.
Look at it this way: Since humans communicate most expressively via natural language, any programming language that aims to be more expressive for its human audience must offer better support for natural language. In the limit, this support will resemble comments, which allow for the full expressivity of natural language. For this reason, comments are inevitable.
Their existence, then, doesn't argue that our programming languages aren't expressive enough, just that humans and machines do not find the same things expressive.
Hmm, actually, maybe. I was thinking about features like dependent types that eliminate the need for a whole class of comments, and that maybe there's a set of features that eliminates the need for all comments. But there are things that computers don't need to know, so there's no reason to encode that in a way they can understand. But-but, if you're writing stuff that one of the two audiences of the program doesn't even care about, are you sure it belongs within the program? (Yes, for other reasons, but it also belongs elsewhere.)
Anyway, sorry, I kind of made up what I meant by "expressive". In the ill-defined interpretation I was using, it's not really subjective, and a language that is maximally expressive would be well-understood by both audiences, and somewhat terse. I don't think such a language can or should exist, necessarily; I don't think the lack of this definition of expressiveness is a bad thing per se. Just that there are different amounts of commentary appropriate for different languages according to how "expressive" they are. (I also don't think that any one particular natural language is the most expressive thing possible for humans, as it rightly makes compromises for efficiency, learning, fallibility, etc., that make room for things like misunderstandings. So I don't think comments are inevitable for that reason specifically, but that's just an aside.)
maybe there's a set of features that eliminates the need for all comments.
I don't think so. The humans reading the code need to know not only what the code does but why it does what it does and why you chose to implement what it does in the way that you did. That information is important for understanding and maintaining the code.
“We use scoring rules from the United States Bowling Congress.”
“Two Newton–Raphson iterations get us close enough to prevent noticeable visual artifacts.”
The ideal form for expressing this kind of essential information is natural language. And it needs to be in the source code, not somewhere else, because your human audience needs to know this information when interpreting the code. Ideally, each tidbit of information would be in close proximity to the code that it supports. Hence the need for some kind of programming-language facility to let you sprinkle that information amidst its associated logic. Hence the need for comments.
tmoertel | 16 hours ago
Thanks for sharing this article! I’ve actually been thinking (and writing) a lot lately about communicating intent when coding.
I agree with the author that, when programming, we ought to be mindful of what our code’s audience will need to know and then make sure our code communicates that information. I think that this responsibility flows from the very purpose of code, which is to instruct a computing device what to do in a form that is easy for the code’s intended audience to understand. It follows, then, that good code must communicate three things: (1) what the machine was instructed to do, (2) what we intended the machine to do, and (3) why we wrote the code in the way that we did. Since programming languages offer only limited opportunities to communicate items (2) and (3) by how we structure logic and choose names, good code usually has some comments. That is why I am not a fan of the idea, popular in some circles, that comments are sign of poor craftsmanship.
tentacloids | 9 hours ago
I agree; comments only highlight the limits of the expressiveness of the programming language. Does this say something about the language's choice of compromise, prioritising neither the computer nor the reader outright? I don't know if it matters how much commentary a language needs to communicate everything that matters. At one extreme, I can easily imagine a language that reads like a research paper, where there could be paragraphs of prose explaining one incredibly dense formula. I don't really know how the other direction would work, if we've even developed the requisite theory yet.
tmoertel | 8 hours ago
Let's examine this for a bit:
I'd argue instead that comments highlight that programs have two simultaneous audiences: the machine and the humans. What is expressive to one audience is not well suited to the other, so programming languages have syntax for both logic and comments.
Look at it this way: Since humans communicate most expressively via natural language, any programming language that aims to be more expressive for its human audience must offer better support for natural language. In the limit, this support will resemble comments, which allow for the full expressivity of natural language. For this reason, comments are inevitable.
Their existence, then, doesn't argue that our programming languages aren't expressive enough, just that humans and machines do not find the same things expressive.
tentacloids | 7 hours ago
Hmm, actually, maybe. I was thinking about features like dependent types that eliminate the need for a whole class of comments, and that maybe there's a set of features that eliminates the need for all comments. But there are things that computers don't need to know, so there's no reason to encode that in a way they can understand. But-but, if you're writing stuff that one of the two audiences of the program doesn't even care about, are you sure it belongs within the program? (Yes, for other reasons, but it also belongs elsewhere.)
Anyway, sorry, I kind of made up what I meant by "expressive". In the ill-defined interpretation I was using, it's not really subjective, and a language that is maximally expressive would be well-understood by both audiences, and somewhat terse. I don't think such a language can or should exist, necessarily; I don't think the lack of this definition of expressiveness is a bad thing per se. Just that there are different amounts of commentary appropriate for different languages according to how "expressive" they are. (I also don't think that any one particular natural language is the most expressive thing possible for humans, as it rightly makes compromises for efficiency, learning, fallibility, etc., that make room for things like misunderstandings. So I don't think comments are inevitable for that reason specifically, but that's just an aside.)
tmoertel | 6 hours ago
I don't think so. The humans reading the code need to know not only what the code does but why it does what it does and why you chose to implement what it does in the way that you did. That information is important for understanding and maintaining the code.
Consider the examples in this article I wrote on the necessity of comments. Here are the first two:
The ideal form for expressing this kind of essential information is natural language. And it needs to be in the source code, not somewhere else, because your human audience needs to know this information when interpreting the code. Ideally, each tidbit of information would be in close proximity to the code that it supports. Hence the need for some kind of programming-language facility to let you sprinkle that information amidst its associated logic. Hence the need for comments.
Comments are inevitable.
tentacloids | 5 hours ago
Yeah, I tried to cover that in the rest of the paragraph (computers don't need to know why you're using them).
Yeah, proximity is one of the "other reasons".
No need to say it like that, I am agreeing with you!
tmoertel | 2 hours ago
Ha! Sorry, I repeated that bit to emphasize that we ended up at the exact same conclusion as before, even though we started with a different premise.
Thanks for the interesting conversation. You helped me to clarify my ideas. I really appreciate it!