Waldo JaquithPlease, please, stop using "foo" and "bar” in code documentation. Give us real examples that mean something. Not "if (foo > bar)," but “if (height > limit)." Not “foo++” but “counter++”. Give us a logical hook to hang our hat on, not nonsense words.
SwiftOnSecurity@waldoj I came across this one time in Wikipedia and it completely ruined the ability to understand what the hell they were talking about. Then I edited the article to use real words and it was immediately understandable
@SwiftOnSecurity Every time I read the jq manual, I get annoyed at how hard it is to follow for this reason. It's a great tool but its manual is really dragged down with all the foo/bar/baz nonsense. https://stedolan.github.io/jq/manual/#Basicfilters
LisPi@waldoj @SwiftOnSecurity It has never made things much worse for me, but I've never been particularly sure why it was a practice either.
Imbolc@lispi314 @waldoj @SwiftOnSecurity I have to say I am a bit baffled that people find the foo/bar convention to be confusing when used to document in a generic way. To me, it is just like the convention of using x in math.
The whole point is they are easy to recognize as things you need to replace.
However I realize some newer programmers consider this convention to be a kind of gate-keeping by us old-timers, and that would be bad. So maybe it is time to stop using our cherished foo and bar.
Nire Bryceit's not that it's confusing to follow (tho it can be), it's that it's way harder to make examples stick in memory compared to names that describe their use. additionally, if your primary language is far from english's pronunciations/word boundaries/etc it makes it a lot more inscrutable. cutesy names aren't worth the cost.
And I've met CS undergrads who don't know. so, seems worth just not using. naming's hard, but you write once and read many
@NireBryce @lispi314 @waldoj @SwiftOnSecurity I agree that if there are names that describe the use, they should be used instead of foo and bar
But sometimes the description is inherently abstract. Take this random example from the invert-kv docs:
Example: {foo: 'bar'} → {bar: 'foo'}
if you used something specific instead like
Example: {size: 'big'} → {big: 'size'}
then the reader might be confused whether the property had to be size or not. With foo/bar it's clear the names are arbitrary
rainwarrior@eob @NireBryce @lispi314 @waldoj @SwiftOnSecurity
In that specific case I think a more distinct pair might help. A typical number key to string value mapping, maybe?
Example: {3: "frog"} → {"frog": 3}
The actual example also throws a rainbow and unicorn emoji in there, which definitely feel like they make the foo/bar problem even worse to me.
Tim Hochberg@eob @NireBryce @lispi314 @waldoj @SwiftOnSecurity I have a certain historical fondness for 'foo' and 'bar', just like I have a fondness for the ridiculous, short shell commands. But I have to admit that it's too cute and a bit lazy. It's not the worst thing you can do though -- some ripgrep docs use NEEDLE, as in "needle in a haystack" which is completely opaque if you don't know the allusion. 'foo' would have been better there, but 'pattern' would have been far better than either.
Fahri Reza 🍉@NireBryce @eob @lispi314 @waldoj @SwiftOnSecurity replacing x with apple will distract new learners with the semantics.
Like, you have 4 apples and split between 2 people, are the apples of the same size, is that fair.
Can't they cut the apples.
RattlesnakeStu@eob @lispi314 @waldoj @SwiftOnSecurity
I've only been programming since 1982 or so, which I guess makes me a newer programmer, and I absolutely hate the foo/bar/baz nonsense. Nothing to cherish in that as far as I can see, but maybe old-timers see something in it that a newbie like me fails to see. From my perspective, it's fundamentally not like a simple letter (like "x"), because a pseudo-word implies meaning that isn't actually there. And that's just FUBAR when trying to grok something.
I've only been programming since 1982 or so, which I guess makes me a newer programmer, and I absolutely hate the foo/bar/baz nonsense. Nothing to cherish in that as far as I can see, but maybe old-timers see something in it that a newbie like me fails to see. From my perspective, it's fundamentally not like a simple letter (like "x"), because a pseudo-word implies meaning that isn't actually there. And that's just FUBAR when trying to grok something.
Ryan Randall@eob @lispi314 @waldoj @SwiftOnSecurity For whatever it's worth: pixels are sufficiently inexpensive that documentation could easily include both!
Ideally, documentation can include the foo/bar abstraction for those it will help, and a "worked example" that demonstrates the pattern applied to a common example.
This "worked example" is how many textbooks introduce patterns. It'd be great for documentation to do the same.
Alexander The 1st@eob @lispi314 @waldoj @SwiftOnSecurity I think the main confusion around foo/bar/baz convention is that although it tells you there are multiple variables and where they map to, it does *not* tell you what those variables could be beyond a possibly unclear typing (i.e. "Foo foo" is less descriptive than "Date foo", but..."Date foo" still doesn't tell me if it's earlier date, later date, or same date value).
@eob @lispi314 @waldoj @SwiftOnSecurity or perhaps TL:DR; All of the confusion of "i, j, k", none of the terseness.
Alexandre B A Villares 🐍@eob @lispi314 @waldoj @SwiftOnSecurity I think there is cognitive cost of imagining what could go in place of foo and bar and replacing it. If you are not a beginner you might not feel the cost. Offering a contextual example makes things easier in some cases, but on the other hand it makes the example less general/abstract which can be a problem too.
Drew@villares @eob @lispi314 @waldoj @SwiftOnSecurity feels like it needs a new dimension convention added to technical language conventions: a distinctly visually different set of symbols for generic variables (entirely different font, which I've seen, or, since all of this lives on the web, even a subtle floaty animation), or alternatively, when read aloud, a different intonation or voice from the rest of the surrounding code (also feel like I've heard this technique used in teaching spoken language)
@dtipson @villares @eob @waldoj @SwiftOnSecurity #AuditoryIcons (https://en.wikipedia.org/wiki/Earcon) might also be usable, for audio interfaces.
#Emacspeak is what introduced me to the concept, where they're used to denote lexical/syntaxic information for programming (among other things).
@lispi314 @villares @eob @waldoj @SwiftOnSecurity love this concept! Given that computers are a few years away from consumer-level being able to live track eyes and know exactly what word I'm reading at any given moment, they could decorate and score the text with all sorts of subtle audio cues that convey meaning
@dtipson They're pretty much already there.
I'd strongly suggest never enabling that in any networked software.
@lispi314 idk, I'm fine with every human and computer on the planet reading along with me, I read great stuff
@dtipson Unless you tightly control exactly what is displayed on your screen & what you read, that'll mostly be used to uniquely optimize spam/ads for your consumption (nevermind all the other privacy implications).
LLMs will make that even easier now.
Mark Tomczak@eob @lispi314 @waldoj @SwiftOnSecurity PROTIP: Math is also bloody inscrutable and has a (well-earned) reputation for being so.
@mtomczak @eob @waldoj @SwiftOnSecurity The notation is useful for brevity for those that already know it, but it sure makes things a lot more complicated than they should be.
shanacodesNaming things is hard. Foo/bar are still used because people writing examples don't want to come up with creative var names for sample code.
I don't find meta metasyntactic var names confusing (and I don't remember finding them confusing as a beginner either), but I still avoid foo/bar in examples because I don't vibe with old military jargon.
⛧TJC⛧@eob @lispi314 @waldoj @SwiftOnSecurity
Yea this is an excellent point. Mathematics is full of short variables. You don’t see “volume_of_cone = …” It’s unreasonable to be ok with mathematical prose but for some reason want super long var names in cs prose.
@tjc @eob @waldoj @SwiftOnSecurity I've actually been thinking that prose should never have been dropped out of proofs and examples in mathematics.
@lispi314 @eob @waldoj @SwiftOnSecurity fair enough, but that is not going to happen. Centuries of mathematical texts are the prior.
@tjc @eob @waldoj @SwiftOnSecurity Yeah, unfortunately (despite even more centuries prior of exactly that being used).
@lispi314 @eob @waldoj @SwiftOnSecurity thought experiment: would you replace the symbol for pi with “ratio_of_circle_circumfrence_to_diamter” and use that everywhere?
Probably not. You would probably write let [pisymbol] =…. Then the brief symbol everywhere. It’s also a brevity thing - without variable substitutions the text would be a much more massive wall of text
@tjc @eob @waldoj @SwiftOnSecurity That is true, although very little text bothers to actually do those let parts for the various symbols. There's just the assumption you know everything.
Wikipedia Mathematical articles are widely considered useless for learning for exactly that reason. "Explanations? We don't need no stinking explanations."
Incognitim@lispi314 @tjc @eob @waldoj @SwiftOnSecurity
Very true- I've done a LOT of math tutoring— ranging from the absolute lowest levels to lower college level— and consistently, one of the biggest issues is not understanding what some arcane symbol or piece of jargon means. Once that hurdle is cleared, it's amazing how many people go from being 'bad' at math to being math badasses.
Very true- I've done a LOT of math tutoring— ranging from the absolute lowest levels to lower college level— and consistently, one of the biggest issues is not understanding what some arcane symbol or piece of jargon means. Once that hurdle is cleared, it's amazing how many people go from being 'bad' at math to being math badasses.
Schrottkatze 
@tjc @eob @lispi314 @waldoj @SwiftOnSecurity yeah and tjose short names in mathematics are the reason i often have to rewrite maths stuff in code with clear naming to understand it. so that shit be gone please too.
Daveography 🇨🇦
Oh good it's not just me who can't make sense of their docs. Just started trying to use jq to solve an issue, now I have three issues.