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

Link: https://github.com/apiaryio/dredd

If real projects were maintained with the same level of human-to-human commuication there would be a lot fewer "legacy" projects. The U.S. is still using air traffic code from the 1960s. The Railroad retirement board has a huge legacy code base they can't maintain. Many other government agencies have the same problem.

In fact, you might run into the same problem if you ever get a chance to write code you wrote 10 years ago. You'll know WHAT it does but not WHY it does it. Literate programming is about writing down the WHY, not HOW.

In the std lib namedtuple which builds a class from a textual template and then calls exec to compile it. You can see the generated code by passing verbose=True in the construction function.

At at much higher level macropy gives you full syntactic macros like you would get in a Scheme or Lisp.

If that isn't enough, there is Hy language which is a full Lisp hosted on Python. Full Python semantics with Lisp syntax, including macros.

However, more often flattening the structure is harder to achieve and one must actually think and experiment with moving pieces around.

I often use early return as illustrated following the principal of avoiding deep nesting. One of my favorite refactorings is adding return to a the first branch and removing the matching else with an outdent of its block.

That is, Python macros are written in Python (and sometimes they are even useful). It also supports goto and multiple inheritance.

I'd argue that Lisp is plenty of inspiration for people to not run away from macros. It's just that we already have a good set of macro oriented languages, so people aren't rushing to replace it.

The trick here is to pick the right dependencies, ones that don't change. POSIX, for example, is stable for a decade. So are most mainstream programming languages. Many core UNIX tools are as well.

I think that it's mostly developers of the low-level infrastructure how should reflect on finishing stuff. If they don't everybody else is screwed.

so when I call
database_cached_attribute :bollocks
database_cached_attribute :silliness
my class ends up with nice to have functions like

invalidate_silliness, only_silliness_changed?, cache_silliness
invalide_bollocks, only_bollocks_changed?, cache_bollocks

etc…

there really is no point to this story other an just go where the current takes you. :)
http://www.macupdate.com/developers/profile/7341

A filter is a Perl module which reads the initial source code and produces the Perl code passed to the final Perl interpreter.

This allows everyone to create its own new syntax or DSL in Perl.

See: perldoc Filter::Simple , perldoc Filter::Util::Call

Then there are true parasites that make the host less fit. For example, the first thing lot of them do is to castrate the host thus bringing its fitness to zero. It's a strategy that works fine as well.