I have this idea that tooling that turns specs into documentation (like Swagger or JavaDoc or whatever) should keep a giant list of apologetic modifiers and prepend them to the front of every paragraph or section or something.

"Unfortunately, this function takes and string and…" "Deplorably, a Segment object is used to model…" "Tragically, a responds code of 304 indicates…"

Bonus points if it sticks, "We're sorry." "So sorry." "We'll try to be better in the future." "We're trying to fix it." and the like at the end.

In looking at the API documentation that my team's been writing recently for inspiration on the kinds of sentences shit starts with I was reminded: Swagger *requires* you to put a version number for your API in there. But we don't, uh, really believe in versioning APIs on my team (I guess @ me if you want). So we put 🏋🏻‍♀️ as the version number and I forgot and then was delighted to discover this again just now.

Oh. Uh. Context: Weight lifting is relevant to the software in question.


totally tangential, but

> (I guess @ me if you want)

is such a Masto thing to say ^_^

I regret to inform you that this method has side effects. The developer comments that follow seem too short to be likely to contain sufficient explanation:

# This was added to pass tests. Not sure why it works

@benhamill "this function takes a string, and might as well be a (badly hand crafted) parser. use it as your first attack vector of choice"

@benhamill "Disgustingly, this function takes a void* and a void** and returns an integer, so who knows what it actually does"

@benhamill "Regrettably, the developer did not include a description of what this method does. Hopefully it is intuitively obvious from the name."

Sign in to participate in the conversation

cybrespace: the social hub of the information superhighway

jack in to the mastodon fediverse today and surf the dataflow through our cybrepunk, slightly glitchy web portal