Sukma Wardana
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.
Andrew Motel@waldoj @SwiftOnSecurity This but also with CLI examples. A bunch of italics and arbitrary brackets and braces gives like 1/100th of the information that a single concrete example would.
Dial Tone, Busy Signal *biiip*@starblind @waldoj @SwiftOnSecurity you are the first person I've seen complain about this... I thought I was alone for like 25 years...
To this day, I can barely understand those man and help pages.
Erwin Rossen 🔸@starblind @waldoj @SwiftOnSecurity That's why I never read man pages, but use a CLI tool called tldr. You type e.g. `tldr grep` and it spits out around 8 examples how to use grep.
Aaron@waldoj agreed 100%. Who ever came up with that should be drawn and quartered.
The Mighty Quinn@waldoj don't you tell me!
Janne Moren@waldoj
"if (bean <= saturday)." Sure can do! 👍
"if (bean <= saturday)." Sure can do! 👍
Martin Piper (he/him) 💙💛🌻💉@waldoj I shall forever use foo, bar, and baz. It is a part of my long term memory.
Ryan Cavanaugh@waldoj this sounds good until you read docs for a language whose syntax you're very unfamiliar with, and it becomes totally unclear which parts of the example are keywords/built-ins of the language and which are user-chosen identifiers
a wandering happenstance@waldoj makes the documentation fucked up beyond all recognition
Joe PasquaCppCon 2019: Kate Gregory "Naming is Hard: Let's Do Better"
arclight@waldoj How many instructors or example writers have domain knowledge beyond code? Look at the number of languages that actually have decent support for physical units. By comparison, we get a new web framework every three minutes.
Dym Sohin@waldoj we could employ the same cloud-to-butt [1] technology which revolutionized google-reader ten years ago
[1]: https://chrome.google.com/webstore/detail/cloud-to-butt-plus/apmlngnhgbnjpajelfkmabhkfapgnoai
[1]: https://chrome.google.com/webstore/detail/cloud-to-butt-plus/apmlngnhgbnjpajelfkmabhkfapgnoai
PHolder 
@waldoj As some of your commenters have implied, these two "words" are variable names that are derived from a long military tradition.. from FUBAR (which I leave to your own efforts to define.) You don't like them, and yes, I agree that examples CAN be made better, but also don't denigrate them without realizing they have 5 decades or more of history behind them. Just like why i, j, k and l are frequently loop variables because of the history of implicit typing in FORTRAN. Know your history!
@PHolder As an exhausting language pedant, I am very familiar with the history. It has zero relevance to my point.
Martin Johnsson@mrtnj @waldoj You know that old saw about opinions, I'm sure.
Continuing with the history lessons I guess: We all have it lucky today where we can have very lengthy names for things. That hasn't always been the case, Microsoft BASIC 2.0, for example, allowed up to two letters for a variable name. And you wanted to keep it short anyway, because the variable names used RAM and 3.5K on a Vic-20 was very limiting. And then of course variable names in machine language are zero characters long.
Hacker Factor@waldoj I fully agree. (Also stay away from variable names like "lambda" or "rho". Spelling out the name of a Greek letter doesn't mean you know the purpose of the variable.)
Foo and bar also bother me because the names come from the military acronym "FUBAR" (pronounced FOO BAR). It means "f*cked up beyond all recognition" (https://dictionary.cambridge.org/us/dictionary/english/fubar). If they wouldn't write "F*cked up" as a variable name, then why would they think "foo" is acceptable?
Hawlucha@waldoj My personal theory is that writing "foo", "bar", and whatever the fuck else tells other computer touchers that you too are part of some special nerd club, like you are in the know.
I wish to not guess what the fuck "foo" and "bar" are supposed to represent. I wish to immediately understand what the example code is supposed to do!
Orc
Chuck O'Rourke:verified:
Sören
Max@Chuck_ORourke @chucker @Hawlucha @waldoj It’s also considered an apocryphal origin by some. The directest technical origin appears to be use as nonsense words in MIT’s Dungeon (commercialized as Infocom’s Zork 1/2/3). Opinions remain split to this day if it was just convergent evolution of “silly sounding baby talk” rather than directly inspired by the military usage. “Silly in-joke words from once classic videogame” seems more likely programming vars origin to me than the “military origin”.
@Chuck_ORourke @chucker @Hawlucha @waldoj Not that the origin matters a great deal, it only distracts from the point that they are primarily nonsense words.
(Further evidence is that in programming vars it is often the nonsense foursome foo, bar, baz, quux or more. baz and quux have no “military origin”, no backronyms. Are about as pure nonsense from Dungeon/Zork as possible to find.)
(If the military origin were more “true” you’d expect foo/bar more in error examples than general examples.)