3 ms·

> I’m not going to list specific examples or tips here, as tastes and conventions differ anyway. There usually isn’t “one right way”. The philosopher in me doe

by dvt 6y ago

> I’m not going to list specific examples or tips here, as tastes and conventions differ anyway. There usually isn’t “one right way”. 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/ https://docs.microsoft.com/en-us/windows/win32/api/winuser/

chopin 6y ago
> 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. 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.
ChrisMarshallNY 6y ago
> I'd argue that more work (at least 50% more) should be put in documenting APIs. Technical writing is a lost art. 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/ https://littlegreenviper.com/miscellany/leaving-a-legacy/ [1] https://littlegreenviper.com/various/testing-harness-vs-unit/ https://littlegreenviper.com/various/testing-harness-vs-unit...
- arp242 6y ago
  I've grown to like unstructured documentation, rather than the more structured headerdoc/doxygen and the like. If you write it well as prose I find it's often clearer. With doxygen it sometimes feel like filling in a bureaucratic form rather than actually writing documentation (and it often reads like it, too).
  - ChrisMarshallNY 6y ago
    Completely agree. The headerdoc stuff is just for a reference.
HelloNurse 6y ago
There are established "ways of doing things" in API design, but they are manifold and conflicting because there are major technical constraints and traditions and more importantly vastly different needs. While, for example, graphical techniques to make interactive elements in a GUI stand out from read-only content are partly universal and partly consolidated by tradition, even a noncontroversial principle like providing "apt documentation" is an abstract concept that can have a very different meaning for different people and in different situations.
slightwinder 6y ago
> 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" 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.
arp242 6y ago
I omitted specific examples as it's just really tricky to make them general. It really depends on the environment, intended audience (kernel programmers are not Rails programmers), and most of all: what you're doing. 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.
- ChrisMarshallNY 6y ago
  Like Apple. They used to set the bar for documentation. Nowadays...not so much (I'm looking at you, SwiftUI).

by dvt 6y ago

chopin 6y ago

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

ChrisMarshallNY 6y ago

> I'd argue that more work (at least 50% more) should be put in documenting APIs. Technical writing is a lost art. 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/ https://littlegreenviper.com/miscellany/leaving-a-legacy/ [1] https://littlegreenviper.com/various/testing-harness-vs-unit/ https://littlegreenviper.com/various/testing-harness-vs-unit...

arp242 6y ago
I've grown to like unstructured documentation, rather than the more structured headerdoc/doxygen and the like. If you write it well as prose I find it's often clearer. With doxygen it sometimes feel like filling in a bureaucratic form rather than actually writing documentation (and it often reads like it, too).
- ChrisMarshallNY 6y ago
  Completely agree. The headerdoc stuff is just for a reference.

HelloNurse 6y ago

There are established "ways of doing things" in API design, but they are manifold and conflicting because there are major technical constraints and traditions and more importantly vastly different needs. While, for example, graphical techniques to make interactive elements in a GUI stand out from read-only content are partly universal and partly consolidated by tradition, even a noncontroversial principle like providing "apt documentation" is an abstract concept that can have a very different meaning for different people and in different situations.

slightwinder 6y ago

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

arp242 6y ago

I omitted specific examples as it's just really tricky to make them general. It really depends on the environment, intended audience (kernel programmers are not Rails programmers), and most of all: what you're doing. 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.

ChrisMarshallNY 6y ago
Like Apple. They used to set the bar for documentation. Nowadays...not so much (I'm looking at you, SwiftUI).