An API is a user interface

Re:An API is a user interface by ChrisMarshallNY on Wednesday November 25, 2020 @05:45AM (#25207841)

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

[1] https://littlegreenviper.com/various/testing-harness-vs-unit...

[ Parent | on HN ]

Re:An API is a user interface by arp242 on Wednesday November 25, 2020 @11:27AM (#25210909)

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

[ Parent | on HN ]

Re:An API is a user interface by ChrisMarshallNY on Wednesday November 25, 2020 @12:16PM (#25211559)

Completely agree. The headerdoc stuff is just for a reference.

[ Parent | on HN ]