Code Complete has a section on this. But we don’t have a precise understanding of what a “good name” is, for the same reason that we don’t have a precise understanding of what a “good song” is: the goodness of a name is measured by its effect on its reader.
So I think the high-level principle, if you want to do a good job naming things in your program, is to model your intended reader as precisely as you can. What do they know about the problem domain? What programming conventions are they familiar with? Why are they reading your program—what matters to them? These concerns will inform your formatting and commenting style as well.
When you draw these distinctions you will exclude some people. That’s normal. You shouldn’t feel badly about that, any more than Thomas Mann felt bad that Chinese speakers had to learn German before they could read Der Zauberberg. If your work is influential enough, someone will translate or annotate it. And unlike a novel, most programs are read only by a small circle anyway.
If you want concrete advice instead of philosophy, this c2 page includes some useful tips.
But we don’t have a precise understanding of what a “good name” is, for the same reason that we don’t have a precise understanding of what a “good song” is: the goodness of a name is measured by its effect on its reader.
I’m not sure whether I buy that argument. It would be quite possible to go out and study naming in the real world and study problems that arise and what goes well.
Yes, I agree. That’s why I like the analogy to composition: most of the songs you might write, if you were sampling at random from song-space, are terrible. So we don’t sample randomly: our search through song-space is guided by our own reactions and a great body of accumulated theory and lore. But despite that, the consensus on which songs are the best, and on how to write them, is very loose.
(Actually it’s worse, I think composition is somewhat anti-inductive, but that’s outside the scope of this thread)
My experience is that naming is similar. There are some concrete tricks you can learn—do read the C2 wiki if you don’t already—and there’s a little bit of theory, some of which I tried to share insofar as I understand it. But naming is communication, communication requires empathy, and empathy is a two-place word: you can’t have empathy in the abstract, you can only have empathy for someone.
It might help to see a concrete example of this tension. I don’t endorse everything in this essay. But it’s a long-form example of a man grappling with the problem I’ve tried to describe.
Code Complete has a section on this. But we don’t have a precise understanding of what a “good name” is, for the same reason that we don’t have a precise understanding of what a “good song” is: the goodness of a name is measured by its effect on its reader.
So I think the high-level principle, if you want to do a good job naming things in your program, is to model your intended reader as precisely as you can. What do they know about the problem domain? What programming conventions are they familiar with? Why are they reading your program—what matters to them? These concerns will inform your formatting and commenting style as well.
When you draw these distinctions you will exclude some people. That’s normal. You shouldn’t feel badly about that, any more than Thomas Mann felt bad that Chinese speakers had to learn German before they could read Der Zauberberg. If your work is influential enough, someone will translate or annotate it. And unlike a novel, most programs are read only by a small circle anyway.
If you want concrete advice instead of philosophy, this c2 page includes some useful tips.
I’m not sure whether I buy that argument. It would be quite possible to go out and study naming in the real world and study problems that arise and what goes well.
Yes, I agree. That’s why I like the analogy to composition: most of the songs you might write, if you were sampling at random from song-space, are terrible. So we don’t sample randomly: our search through song-space is guided by our own reactions and a great body of accumulated theory and lore. But despite that, the consensus on which songs are the best, and on how to write them, is very loose.
(Actually it’s worse, I think composition is somewhat anti-inductive, but that’s outside the scope of this thread)
My experience is that naming is similar. There are some concrete tricks you can learn—do read the C2 wiki if you don’t already—and there’s a little bit of theory, some of which I tried to share insofar as I understand it. But naming is communication, communication requires empathy, and empathy is a two-place word: you can’t have empathy in the abstract, you can only have empathy for someone.
It might help to see a concrete example of this tension. I don’t endorse everything in this essay. But it’s a long-form example of a man grappling with the problem I’ve tried to describe.