On Sat, May 5, 2018 at 3:08 AM, Sean P. DeNigris <s...@clipperadams.com> wrote:
> Richard Sargent wrote > > No. Please, really no. > > As much as I appreciate (and share) the passion for Smalltalk, you did not > AFAICT address my reasoning for not applying the no-acronym *guideline* in > this case, namely: > > >> Since the argument IIUC is that "a > >> general user won't know the domain well enough to understand the > >> acronym", > >> would they understand "abstractSyntaxTree"?! That, to me, is as opaque > as > >> the acronym for one not acquainted with the domain, and may buy us > little > >> at the cost of a good amount of extra typing. > I care a lot less about typing than reading. Some years ago, a colleague of mine conducted a brief and informal survey of the developers working in our team. "What fraction of time do you spend reading code versus writing code?" Some people answered 50:50. In effect, saying that for every method they read, they wrote a new one! The truth is that we all spend substantially more time reading than writing. Consequently, we need to emphasize how we communicate to readers. Alan Knight said it best: (paraphrasing) Trust the implementation does what it says it does. (In other words, message names should do what they say they do without creating the need to look inside the method to understand it.) > > > Richard Sargent wrote > > a disambiguation page with a lengthy list > > IMHO this is irrelevant. My proposal included a method comment, which would > provide the google-able term, as well as potentially a good enough summary > that one wouldn't have to leave the image. The fact that the method belongs > to CompiledMethod is the disambiguation. The internet is meaningless and > flat compared to the context and structure of a ST image. > > > Richard Sargent wrote > > Do not use comments embedded *inside* methods to cover for naming the > > method badly… Also, if one Googles an acronym > > How is a harder-to-type thing that the user doesn't understand but is > easier > to google better than a comment that gives the necessary context right in > the image? My ideal image would avoid the need to Google as much as > possible, suggesting a comment either way, so nothing lost. There's nothing > inherently "bad" about an acronym. For example, no one's been banging down > the door to rename "JPEGReadWriter" to > "JointPhotographicExpertsGroupReadWriter". In that case, it's because the > acronym is so well-known, but what I'm asking whether #ast is a similar > candidate for exception because it is so unknown (i.e. compiler > domain-specific) that a user is likely to know either the term and the > acronym or neither. > The thing is that a well named concept doesn't need Googling in order to have at least some understanding of its meaning. I would be willing to bet that, even if you had never heard of the topic before, you would have *some* idea what the phrase abstract syntax tree meant. Conversely, the first time one might encounter the concept presented as "ast", you might suspect it was a kind of snake. I'm being a bit extreme here, of course. > > > ----- > Cheers, > Sean > -- > Sent from: http://forum.world.st/Pharo-Smalltalk-Users-f1310670.html > >
