oooor you could just stuff it all in the square hole 😁

But seriously, I like the approach. I tend to go overboard with my type definitions sometimes, because I feel like it saves me some thinking down the line, and conversely get frustrated when the tools for it are limited.

My first foray into the world of programming was a python book for kids. Among other things, it featured an example for multi-line strings that contained the line “Explicit is better than implicit”. Aside from the irony of quoting that in the context of python (I believe it was written for 2.4 or 2.5, before explicit typing was even supported), it stuck with me.

I think that somewhat reflects the “parse, don’t validate” advice I found somewhere. I’ll look for the link and edit if I find it (edit: I did!) but the idea is something like “when a value first enters your code, parse it into a type / struct the rest of your code proceeds to use”. That way, you check “does this make sense as a port number?” exactly once, throw it right back at the source if it doesn’t, put a “yep, this fits” stamp on it if it does and never worry about it again, thus saving repetitive boilerplate code.

Good luck!

I had something similar to that with Power BI DAX where the same “intuitive” structure (a table definition) had different syntax for two similar purposes.

The inline table constructor for a single column table is {value, value, ...}, with the column just named “value”. The constructor for a multi-column table is {(value, value, ...), (value, value, ...), ...}, and the columns are named “value1”, “value2” and so on.

The function DATATABLE allows both specifying the column names and types for the data. The syntax for the data argument is {{value, value, ...}, ...}.

If you can spot the difference, you will have figured out why simply transplanting my constructor into a DATATABLE didn’t work, but copying an example and replacing the values one by one did. It took me way too long.

Maybe you just missed some nuance your brain skipped over?

Can you create a paper trail about an impending issue caused by his creation, then let it fail in prod and hopefully get the right people pissed at him? Or is that more likely to backfire on you instead?

So they’re kinda gambling too, except they’re playing poker and the cards are stacked in their favour?

I think you’re spot on, and this is the reason I put “controversial” in front of it.

And I just can’t resist a good invitation for some discussion. Thank you for providing it!

How many dictionary lookups deep are people reasonably expected to go? Depending on the reader, there’s just some level of complexity that isn’t accessible any more. Add to that the diversity of mental models and approaches people take and a semantic structure intuitive to you just won’t work for someone else, no matter what words you use. Don’t get me wrong, you can’t cater to everyone and I’m not sure you should if you could.

I understand that your target audience are typically people already familiar with or at least invested in the subject matter, in which case leaning on a presumed funamental understanding and a willingness to fill gaps is sensible. You don’t want to bloat your docs by repeating things your most relevant readers already know.

In doing so, you “sacrifice” the accessibility for less versed people. In a perfect world, we wouldn’t have to choose and everyone would get an explanation suitable to their own level of understanding and background. Alas, our world imposes limits on our knowledge, abilities, time and energy. Readers and writers alike should be aware of those limits, both in themselves and in each other.

I feel like “Skill issue” understates the complexity of the combinatorics the diversity of human minds produces. It’s a human issue that might never be perfectly solvable. Your solution is good and appropriate, and that has to be enough.

My point is merely that we should be aware of the downsides of our choices and make that tradeoff consciously.

So I assume that most of the backend did actually surface error codes via the HTTP layer, it was just this one endpoint that didn’t

How is this getting even worse still? Why would a single endpoint work differently? That suggests they have standards, just one arsehole decided to shit on it and the rest didn’t vet their code enough to catch the issue.

otherwise basic testing would have caught it

I worked QA in a small dev team for two years. You might be surprised how uncomfortable you can make some developers within five minutes of “basic testing”. By the time I left, the team lead loved me as much as some of the devs must have hated me.

frontend expects the backend to return errors, but the backend lies and says everything was successful, and then certain things break in the UI

That’s a double failure then: not only does the backend do it wrong, the frontend devs don’t even know it. If they’d agreed on one way of handling it, they’d still be able to work it out. But if the devs don’t even communicate their standards with each other and the frontend devs obviously don’t know about the problem…

devs love to argue abt this shit

Devs and standards have a contentious relationship.

If I develop something, I obviously know what works best for me, so I don’t want to be constrained by some dumb standard. If someone else doesn’t follow them and it makes things harder for me, they’re a clueless fuckwit that shouldn’t be allowed near a computer ever again.

Yes, that’s a double standard: I don’t even have a standard when it comes to handling standards.

The main difference being that code is typically stored in plain text files, where you can more easily compare and merge differences, while some other document types are harder to diff usefully. That doesn’t mean you can’t use git to keep their version history, it just means resolving merge conflicts might be a bitch.

This is really damn good. Thanks for sharing it!