But there's a lot of other rules (of thumb) to follow. This is quite a good presentation: http://lcsd05.cs.tamu.edu/slides/keynote.pdf

It is generally about documenting and sharing problem-solving knowledge. As you note, this means one sort of thing for a computer scientist writing a paper, but something more pragmatic to an end user or business.

The software evaluated in this research was more of a traditional spreadsheet and GUI design, but other work looked at a test-based approach with something like Markdown. Something similar is going on in the data science community with "notebook" tools like Jupyter and Beaker.

I tried to use Babel, as mentioned in another comment, but found it too bloated and complex. My approach is pretty simple in comparison: code blocks can be annoted with a shell command, which they're piped into, eg.

‘``{pipe="python"}
echo ’Hello world'
```

Most actions can then be achieved in a regular Unix way (eg. by reading/writing files, calling programs from scripts, etc.)

As for the monkey part, yes, it's an exageration. But let's be frank: It's not quntum physics. If you've been programiing for a decade or two you can probably hack together a bearable API. Assuming that the political aspect have been settled in advance, of course.

In your first sentence:

"I've browsed resources about API design".

You go on to talk technically about how:

"APIs are just functions…"

and then how there can be

"messy APIs with ragged borders…"

So it would seem that you are pretty focused on building APIs and API design.

API design is 0% political and 100% technical. How APIs are exposed, how they are organized, how they are developed, how they are documented - it's all technical - 0% political.

The 100% political part happens at the product level where you have stakeholders pushing and pulling with each other on who the API is for. This is not API design. None of the product (political) stakeholders will tell any of the engineers how the design should look - because that's a technical issue.

This is the least responsible statement in your article:

"solve it [politics] and the rest of it can be done by a monkey"

If all product politics surrounding an API are wiped out, I can guarantee you 100% that an API will not, and cannot, be properly designed and implemented technically by a monkey or even a junior developer for that matter.

As for the question, I would use goto. It's much more readble than do/break/while(0) construct.

 if (obviously_no_result(request)) return null; calculation = check_something(request); if (calculation_shows_no_result(calculation)) return null; if (more_expensive_check_shows_no_result(calculation)) return null; full_calculation = expensive_full_check(request, calculation); if (!full_calculation) return null; result = get_result_structure(request, full_calculation); notify_hooks(result); return result; 

i.e. the fact that additional calculations are needed between ifs means that else-if cannot be used, and the performance hit of putting all calculations up front is unacceptable when most calls will (intentionally) fail.

I've used this style for 20 years for efficiency and clarity. It is much more clear than 'only return once' style code. When I wrote a textbook with an example using this style it garnered a bad Amazon review from someone who complained it showed I was a terrible programmer, because I didn't follow 'best practice' as taught in their Java course. Not that I'm bitter, or anything…

The complaint is that, if I need to do something for every failure (like adding a log, say), it is easy to forget a place to add it. I'm increasingly thinking that goto is actually a pretty good solution, and labels are a form of documentation. Though my need to be seen as non heretical probably stops me from using it in anger:

 if (obviously_no_result(request)) goto no_result; calculation = check_something(request); if (calculation_shows_no_result(calculation)) goto no_result; if (more_expensive_check_shows_no_result(calculation)) goto no_result; full_calculation = expensive_full_check(request, calculation); if (!full_calculation) goto no_result; valid_result: result = get_result_structure(request, full_calculation); notify_hooks(result); return result; no_result: notify_error_hooks(request); return null; 

More details here: http://250bpm.com/blog:16

TL;DR: I've never got the patch merged to Linux. If you have any free time to spend you may try to push it through yourself.

Anyway, it'll be hard to decompose politics into building blocks. Any system proposed will be gamed if it gets adopted. That's the nature of politics, I am afraid.

Politics of APIs - http://apievangelist.com/2014/03/17/politics-of-apis/
Politics of the API Economy - http://apievangelist.com/2015/07/27/politics-of-the-api-economy/
API Evangelist Thoughts On The Right To An API Key And Algorithmic Organizing - http://apievangelist.com/2014/09/06/api-evangelist-thoughts-on-the-right-to-an-api-key-and-algorithmic-organizing/

I don't believe need to stop kidding ourselves about APIs, we need keep having discussions about why they work, why they don't, and the common building blocks that make things go around.

Something I've been working on for over 3 years.

Kin Lane