I’d suggest 100% more.
I use headerdoc (Doxygen-style) code comments all the time[0]. That helps, but is not perfect. It’s still better than nothing.
Structuring an API, so that the internals are sequestered, is (IMNSHO) important. I like to have the lions’ share declared private or protected.
Test harnesses (as opposed to unit tests) are pretty effective examples[1].
[0] https://littlegreenviper.com/miscellany/leaving-a-legacy/
[1] https://littlegreenviper.com/various/testing-harness-vs-unit...
For example, sometimes a single function with 5 parameters would be bad UX, whereas in other cases it might be a good option, if all 5 really are mandatory for example, or if you use Python and have named parameters. In other cases, it makes more sense to have 5 functions which accepts a single parameter (no one likes "foo(true, true, false, true, false)").
Not all GUIs are the same either; specialist tools can get away with certain "difficult" UI conventions, since people will be trained for those tools, whereas GUIs can't. A lot of design choices are trade-offs without a single objectively "best" solution.
I actually trimmed down the article quite a lot from the original draft I wrote over a year ago, since I didn't want to get bogged down in "details" about these kind of things, as I could think of a whole bunch of exceptions for every general piece of advice. So instead I opted to try and get the bigger point across that an API (any API) is something humans need to interact with, and is a "user interface".
As for documentation: yeah, I agree. I actually like writing documentation and I'm often dismayed by the poor quality documentation out there, even from people or organisations I know can do better.
Nowadays...not so much (I'm looking at you, SwiftUI).
There are definitly things you should not do, but there hardly is a list ot things you always should do. There is just no gold list of thing in UI, just customs and established conventions to enforce the "intuitive level" of interactions.
But even between different platforms you have strictly different conventions, sometimes even competing with each other. Yet most of them are good on their own and it's wrong to use one of them.
> after 50-odd years of user interfaces, we ended up with scrollbars and buttons and tabs for a reason.
Yet wie have working interfaces without scrollsbars, buttons and tabs, even where they could be used, and some cases where using them even makes the interaction worse.
UI is more a kind or prioritylist of things you can add, not a checklist of things you should add.
I'd say that the 'proper' API design depends very much on the language you target, at least when you come to details. However there are a few overarching principles of UI design which also hold for API design such as consistency (in my view the most important part of UI design) or discoverability.
In my view resorting to documentation is a second line of defense. The first line being able to understand intuitively. This is one reason I prefer libraries over frameworks. The latter almost always require documentation for working with them (you need to implement these 5 interfaces and put them into this factory,...). The former done right are almost always intuitively understandable.
The philosopher in me doesn't mean to be snarky, but what the author concedes here is that APIs actually aren't like user interfaces. Because when we're talking about UIs, there are most definitely "ways of doing things" and "ways of not doing things" -- after 50-odd years of user interfaces, we ended up with scrollbars and buttons and tabs for a reason.
The point is interesting, but lacks force without actual examples. APIs can vary immensely in application: some might take huge arrays of data, others might take neatly formatted arguments, others might just consume bit streams. There's certainly a point to be made about the ergonomics of an API, but -- even though I may have an intuitive feel for it -- I'd need to think more about how to exactly explain what I mean. I have a feeling the author is in the same boat.
Further, there's a fundamental element of documentation when dealing with APIs. Even the most unwieldy[1] API can be grokked if documentation is apt. I'd argue that more work (at least 50% more) should be put in documenting APIs. Technical writing is a lost art.
[1] https://docs.microsoft.com/en-us/windows/win32/api/winuser/