250bpm

The most critical rule, IMO, is the "rule of three".

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

Addressing this problem is the basic idea behind this research: http://ieeexplore.ieee.org/xpl/articleDetails.jsp?reload=true&arnumber=6344472&filter%3DAND%28p_IS_Number%3A6344456%29

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've written a couple of literate programming plugins for Pandoc ( http://pandoc.org ), which I've written about at http://chriswarbo.net/essays/activecode/index.html

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.)

Great post!! Can you recommend good resources that you came across re:API design?

Well, that's how it should be. Solve the political problem, then design the API based on that. But unfortunately, that's rarely the case.

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.

Hi author,

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.

Indentation fixed.

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

Most of serious C code uses goto for error handling. I wouldn't worry much about being seen as a heretic by C++/Java people. Just tell them to check the C best practice.

In particular I often have code that looks like this:

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;

I've actually tried to do that. Note however, that it requires a change to the kernel.

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.

Isn't it possible to make the channels compatible with select(2) ? Being able to copy the go syntax is nice but I think will prove to be more of a headache in the long run. It's actually an annoyance that I have in go: select doesn't allow to mix channels with IO objects forcing the user to create goroutines to feed the latter into the former.

Fixed. Thanks for spotting it!

"George Martin likes to slaughter his caracters "
caracters -> characters.

Hi, good to know that there's someone out there who thinks about the problem. It's not at all that common.

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.

The issues you discuss are real, and something being realized and worked on by many. Your title is linkbait. ;-)

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

Clojure is a modern reincarnation of lisp that has a decent support for macro.
And, macro is fine in the lisp languages.

Looking forward to the answer to that question. I am interested in the interaction of software to the users of the software and how they can adapt it.

Sorry about the broken formatting, I didn't realize the indentation will collapse and I can't edit the post now. INDENT(1) is your friend… ;-)

if do_stuff*() require a lot of surrounding context so cannot easily be factored out into a seperate function, would you advocate for using break over nested if()s?

void
foo(void)
{
  setup_do_stuff_context();
  do {
    if(condition1()) {
        do_stuff1();
        break;
    }
    if(condition2()) {
        do_stuff2();
        break;
    }
    if(condition3()) {
        do_stuff3();
        break;
    }
    do_stuff4();
  } while (0);
  teardown_do_stuff_context();
}

A big problem with languages that allow macros is that they make it very hard to write static analysis tools for them. Having macros also means that the syntax of the language isn't fixed, just look at all the trouble the C preprocessor can cause (#define BEGIN {) or how godawful (La)TeX is. There are real reasons why people have turned away from macros.