this post was submitted on 26 Aug 2024
1187 points (99.2% liked)
Programmer Humor
19463 readers
263 users here now
Welcome to Programmer Humor!
This is a place where you can post jokes, memes, humor, etc. related to programming!
For sharing awful code theres also Programming Horror.
Rules
- Keep content in english
- No advertisements
- Posts must be related to programming or programmer topics
founded 1 year ago
MODERATORS
you are viewing a single comment's thread
view the rest of the comments
view the rest of the comments
Still bad, i'm not a computer with a lookup table in memory.
What is "eng"?
Lol fair point regarding Eng: "Engineering".
But Nah, I think assumed knowledge of PV=nRT is fair in context, since if you don't know what it is, you'll only be reading the conclusion, not getting into the weeds of a calculation document.
I'm not going even going to be explaining if I have a column that's says volumetric flow rate, with V=m/ρ. If I give mass flow rate and density (with units, of course), and use these extremely common symbols, and someone doesn't understand, then they have no real business getting to this level of detail anyway.
I do agree that in most cases not defining your variables is bad practice, but there is some nuance, depending on the intended audience and how common a formula is, and the format of whatever it is you're writing.
So, in the end you just do assume everyone to know the "common sense" one-letter notation for everything. Well, not everything, but the essential ten thousands of entities for sure /s
This sounds like No true Scotsman fallacy to me
I find it a bit contradicting to the very point you made about defining variables. If anything, one might be some home-grown genius that has real business getting into details but only ever used Chinese characters as variables
Edit: forgot to set language
Understand your frustration with how I've communicated my position, sorry about that:
My justification for the examples I've given is there still needs to be other context, is based on complexity of the equation, and the intended audience of that equation.
An example of me not explaining a very simple equation would be perhaps a table of various cases:
|
| mass flow (kg/hr) | density (kg/m³) | Volumetric flow (m³/hr), V = m/ρ | | Case 1 | blah blah | blah blah | blah | | Etc. | ... | ... | ... |
Realising now that markdown tables don't seem to work 😅, hopefully this is still clear.
It may be a touch better to put variable symbols in the other columns, but:
As a recent example for this, in a data sheet I recently prepared, I literally just put a * in the references column and said "*calculated from other data sheet values" for the volumetric flow rate, because the intended audience would know how to do that, and the purpose was for me to communicate how that value was determined.
Me putting in the V = m/ρ in the hypothetical example I gave above is a just a little mind jog for the reader.
Where more complicated equations are used, of course these are properly referenced, usually even with the standard or book it's come from.
I'll redefine my position to: Clearly define all variables, unless it's abundantly obvious to your intended audience from context.
My intended audience of the conclusions or final values are the layman. My intended audience of everything else is someone with a very basic chemical engineering understanding.
Your last point is a strawman:
Because I'm writing in English, for an English speaking audience, and there is no such thing as a home-grown genius getting into my area because it's a legal requirement that they have an honours degree. Even still, the two assumed knowledge equations I mentioned, which I would only not reference with sufficient context, would STILL be recognisable with totally random symbols.
| mass flow (kg/hr) | density (kg/m³) | Volumetric flow (m³/hr), 容 = 质/密 | Yup, a bit odd in an English context, but with the units information (always mandatory, of course) completely understandable.
First of all, thank you for a thoughtful response, I was too snarky, sorry about that.
TL;DR: guess I'm just upset that there is no objective way of measuring how much knowledge is required, and trying to read everything from sources list would take forever.
Yeah, the last point is sort of a strawman, although I meant it not to highlight that explanations should be given in terms that the reader is used to, but rather that the reader may have quite arbitrary amount of prior knowledge.
I agree that there probably should be some shared context, what bugs me is that people tend to vary a lot in what amount of context is considered to be required. And more than once have I met papers that require deciphering even if you have some context and kind of come from the field they are written for. I used to think that this is our of malice to make reproducing their work harder for others, but maybe it was just an assumption of much larger shared context.
Tables markdown work in some clients, afaik, but I don't remember which, and even if I saw it or imagined it
No worries friend, no hard feelings and appreciate the engagement!
Yeah, agree it is a bit wishy washy in terms of gauging how much explanation to include ¯_(ツ)_/¯
I suppose (in my opinion) the mindset should be: include as much explanation as possible, without it being cumbersome.
I personally err on the side of over-explanation and have had some senior engineers give me feedback that it's too much. Still learning for myself how much is too much.
Totally agree though, that there are many cases where people leave things out as assumed, when it's not really reasonable to do so.
A side-thought on specificity: one of my biggest pet peeves is when people list pressure with the units of kPa, when they really mean kPag. In industry, you are rarely talking in absolute pressure (other than for pressure differences) and people then get lazy/don't know/assume it's fine to do something like: set point 100 kPa (when they mean 100 kPag). It isn't fine though, because at lower pressures atmosphere counts for a pretty large percentage of the absolute value.