Hacker News Reader

Comment by imgabe | Hacker News Reader

I seem to have this problem a lot with Apple’s docs. So much of it is like

    Nargflargler: Flargles the narg

You need to do something besides repeat the name in the definition.

View on HN

This is just one example of how metrics can distort things, of course. Someone in management said "We want 100% documentation coverage of every method," so the staff dutifully wasted everyone's time by writing "setDefaultOptions: sets the default options". It's the kind of thing an LLM could have done better, and if you know my opinion of LLM's, you'll know that's damning with faint praise.

My own bete noire here is MSDN. It's full of overloads like "Foo(string parameter, FooOptions options) - actually useful documentation. Foo(string parameter) - does Foo with default options." But to find out what the default options actually are, you have to find another page, probably the FooOptions constructor. I wanted the default options to be mentioned on the "Foo(string parameter)" page, and they so rarely are. (A few pages are better, thankfully).

> But to find out what the default options actually are, you have to find another page, probably the FooOptions constructor. I wanted the default options to be mentioned on the "Foo(string parameter)" page, and they so rarely are.

It's better for maintenance (of the documentation) if the default options are only described in one place. (If the defaults change in a new version, this ensures the documentation doesn't have inconsistent, wrong descriptions. The analogous reasoning, applied to the code, is probably part of why the FooOptions class exists in the first place, after all.) But they should do you the courtesy of linking there.

But that could be linked up rather than have you fumble through to find them.

This is only a problem if you write it twice. Instead you can write it once and display it twice.

Hell, I even do this on my github.io website that uses markdown. You can just write some text in one document and read it in another.

We're programmers, so we should be lazy. It's about being the right lazy. You can be lazy by putting of a task today that takes more effort tomorrow or you can be lazy by doing a task today that takes less work than it would take to do tomorrow. Most people choose the former and wonder why they have so much work. In programming if you're doing redundant work then you're probably being the first type of lazy

In code documentation doesn't support such thing. And documentation outside of code suffers from rot.

Some varieties of in-code documentation do support links, e.g. XmlDoc which is the de facto standard for documenting C# code (and therefore the most relevant to my comments about MSDN because I was referring specifially to the .NET API documentation) has multiple ways of embedding links in your in-code documentation comments: https://learn.microsoft.com/en-us/dotnet/csharp/language-ref...

MSDN even uses those, a lot. But not enough. I wish that every time they had a "Foo(string parameter) - uses the default FooOptions" it was a link to the documentation section where the default FooOptions are listed. But usually you're left to find the default FooOptions yourself, which means 5-10 minutes of digging through docs (1-2 minutes if you're lucky) that I could have spent writing or reviewing code instead. That adds up.

We are talking about MSDN not some source files. Even if those pages are generated from in-code documentation that generation step can use whatever transclusion mechanisms Microsoft wants to add.

And then there is Microsoft's annoying habit of creating APIs which return the information you actually need . . . nested three levels deep inside a bunch of their own custom data structures.

I've basically resigned myself to "it makes sense in Redmond somehow, even if it makes no sense to me."

Microsoft's APIs basically shove all the implementation details onto the API user. This is, of course, abysmal API design, but "tasteful design" (in any sense) and "Microsoft" have never been in the same building. But it does make sense. And it also tells you how to interact with Microsoft APIs: the same way you interact with the hardware details that assembly languages export to the user, namely through a wrapper. (But, taste is difficult to find; that wrapper might have imbibed some Microsoft "design" by virtue of being exposed to too much Microsoft.)

Rant: if you want antialiased text, you need to use Direct2D. Direct2D is one of those APIs that waste developer's lives. You have to allocate your own framebuffer, for crying out loud. And then, you have to reallocate it if it ever disappears for some reason, and the docs don't tell you when this might happen (hot swap a video card? change monitor resolution? User moves window to a monitor with a different video card?).

I found this out developing a cross-platform UI library, https://github.com/eightbrains/uitk, leading to my above conclusion that the only proper way to relate to the Microsoft API is through some layer.

In some fairness, the page existing at all is half the battle. I'm glad the canvas exists for the paint to eventually, maybe, one day arrive.

Related to this is the omitting of units. I encountered something like this in the Android SDK (years ago, dunno if it’s still like this).

    setFontSize(float): sets the font size.

Cool. Sets the font size in what? Points? Pixels? Device-independent pixels? Which of the 12 different types of measurement Android supports is used here? I can’t remember exactly what it turned out to be, but I know it wasn’t the unit I expect for fonts (points).

In similar cases (maybe not exactly here), I suspect the author also didn't know and didn't care to look it up and just wanted to tick the box that it's now documented.

That's more about API design than about documentation though, as with a proper function name/using value objects/something else, you already know what the correct value to pass is.

It's a widespread issue though, where the API designer doesn't clearly communicate either what the thing does and/or what the thing needs.

If you don't need the docs then you don't need them, but sometimes we all need a "hey bro, I know you're a little lost so I'm going to break down what's happening in plain English". At a certain point you just don't have the entire code base in your head all the time and you need a reminder on what exactly the Flargle team does to all the Nargs.

This is why I'm sad that hungarian notation has gained into such a bad reputation. Sure, you can overdo it, but a `duration_ms` or a `response.size_bytes` or a `max_memory_mb`, or an `overhead_ns` is so much easier to use.

Better yet would be unit-aware types. Then instead of

duration_ms = 1000

you can have

duration = 1s // or duration = Seconds(1) in deficient languages

and it's either a compile error or the type system enforces the correct conversion.

As for the bad rap of hungarian notation, it's mostly from people using it to encode something that is already clear from the types. "fDuration" helps no one over just "duration".

But that's what the actual hungarian notation was about: decoding the type of thing it represents not the data type used.

This is why I rage against the crowd that promotes "self documenting code". There's no such thing, even if you should strive to make your code as readable as possible. But if there's a way to misinterpret it then you can bet many people will.

The biggest problem is that this ends up creating so much extra work. An extra 2 seconds from the dev could save hundreds or even thousands of people hours of work. I can't tell you how many hours I've spent chasing stupid shit like your example. I don't know a single programmer who hasn't.

I just don't understand why everyone's frustration with documentation (or lack of) doesn't make obvious the importance of good documentation. Every single one of us has experienced the wasted time and effort that results from the lack of documentation or from low quality docs. Every single one of us has also reaped the benefits of good documentation and seen how much faster it makes us. How does anyone end up convincing themselves that documentation is a waste of time? It feels insane

Code can show you HOW something is done. Only documentation can explain WHY it is done that way.

This kind of bad documentation is actually way more common in teams that require doc comments for all code, which are then promptly auto-generated by the IDE and never filled with actually useful information.

Self documenting code in this case would mean using a type that encodes the unit - which would have the additional benefit that the compiler or other tools can now check correct usage.

You're misinterpreting

Requiring docs isn't the cause of the problem. It's the lack of enforcing quality. The difference is that you're looking at the metric and seeing Goodharts Law in action while there's nothing preventing you from going beyond the metric. That's the real issue is that metrics only take you so far. No metric can be perfectly aligned so it's up to the people who are evaluating the metrics to determine if the letter of the law is being followed or the spirit of it is. If you do the latter then yeah, maybe some functions will be left without docs but you also won't hasn't those tautological docs either. If you only care about the letter of the law then you should expect the laziest bullshit as Goodharts Law always wins out.

Stop reading too much into metrics. Metrics are only guides

> There's no such thing

Not in general, but here it could be called:

    setFontSize (dvi_pixel_t size);

AVMetadataKeySpace

A structure that defines a metadata key space.

source: https://developer.apple.com/documentation/avfoundation/avmet...

That’s just a C enum interfaced in Swift. You can’t instantiate it, and it has no methods or any kind of functionality. It’s effective a list of numbers.

What are you expecting the documentation to say here? It will make more sense when you find where it’s used.

Edit: First link on the bottom explains exactly what it’s used for. https://developer.apple.com/documentation/avfoundation/retri...

struct AVMetadataKeySpace - a unique unit representing each of the metadata key spaces supported by AVFoundation.

? Did you read the link? It’s used to query collections of keys grouped by the KeySpace categories, instead of a single item per key. Makes sense to me.

There’s plenty of other poorly documented Apple APIs (io_surface), but this isn’t one of them.

The struct is only named on the link you provided, not documented. So thanks for showing the absolute irony of it not being greatly documented, allowing people to misinterpret what it means.

Because it’s a boring enum in C, auto translated to a swift struct.

And if you’re reading the documentation because you do development, then you would already know that the header files are installed on your computer and you can trivially verify that there is nothing to document because it’s just a query key.

Enums get documented everywhere else. If nothing else, you need the range of options!

Going off to read the header file means it isn't documented.

> It’s used to query collections of keys grouped by the KeySpace categories

Sounds like something that should be mentioned in the opening sentence of https://developer.apple.com/documentation/avfoundation/avmet...

Not quite what you're talking about but this Apple doc page has always amused me: https://developer.apple.com/documentation/contacts/cnlabelco...

I have to assume that there exists some language where that relationship is described in one word, but it hurts my English-oriented brain.

There are indeed languages that don't have the word "cousin" -- or "uncle" or "aunt".

But I would bet that those variable labels are never translated into other languages.

Presumably those enums are used to select localized labels and you need all these cases to cover unique words / phrases that exist in the supported languages for specific familiar relations.

And conversely, there are languages with different words for "father's sister" and "mother's sister", and for male vs female cousins, etc.

And we don't even have to get exotic for that. My language, Danish, is just a run-of-the-mill Germanic language and those terms are "faster", "moster", "fætter", and "kusine".

Some of the East Asian languages are crazy regarding terms for family members. It's like learning foreign words for plants: I just give up. I will not even attempt to learn them.

There are also languages where the relative age difference changes how you address a relative. Like if your father is older or younger than their sibling, the way your address that uncle or aunt changes. There is another way you address them if they are the oldest or youngest uncle/aunt. Similar but slightly different on the mothers side.

Or with Xcode, go to fargler settings click on narg screen. Took a year just to figure out most setting screens

> with Xcode, go to fargler settings click on narg screen

I hate how this looks "accessible" to people in theory, but in reality finding those screens is more like playing a hidden object game.

Also, I hate how those things keep changing around in all kinds of software, but especially Apple. Somebody probably thinks "yeah maybe we should move the Fargler settings from the Narg to the Birp screen", and makes dozens of internet "documentation" (and sometimes their own!) obsolete.

Apple documentation reminds me of an argument I got in with an elementary school teacher over a textbook… it went on for weeks

> A prepositional phrase is a phrase with a preposition in it.

> A preposition is a word in a prepositional phrase.

One problem I remember from (briefly, fortunately) dealing with Apple APIs is wondering incessantly why every API (I was looking at) started with NS. Admittedly these days any AI would tell me it stands for Next Step. But if you are creating a new thing with a quirk like this please explain it once, in a place that's easy for the student to find.

The more useful answer is:

a) it needs namespaces

b) but giving people namespaces is unironically bad because it's what lead to "enterprise development" style APIs like C# where everything is named System.DataStructures.Collections.Arrays.Lists.ArrayList, as if giving something a longer name makes it more professional.

c) so instead two letters means a system framework and three letters means a user framework

I quite like a terse but consistent conventions myself. I remember finally being able to quiet the tedious part of my brain that couldn't get past the NS conundrum when I finally came up with the NextStep thing as a reasonable theory.

In other words, my only complaint is that this Apple convention is not more easily discoverable. Or perhaps that the expert author of the book I was reading (this was back in the day) didn't feel the need to share it with his readers.

Its a standard thing to do in C. You generally use a prefix of 2-4 characters from your project name.

Triangle theTriangle = new Triangle()

Lives rent free in my brain.

The issue here is that people are treating reference materials as tutorials intended to cover your exact concern at the moment. You are expected to know what a narg is and what flargling means. In more real terms, the documentation for screen savers https://developer.apple.com/documentation/screensaver?langua... won't explain what a view is, what subclassing is, or what a Rect is. Those are required knowledge to consume the documentation and it's not a documentation failure that this is true.

No, you missed the point. The problem isn't "narg" or "flargling" - those are just random stand-ins for normal words. Instead the problem is that the description says nothing that isn't already said by the symbol name. Whether or now you know what "narg" and "flargling" mean, a documentation page for Nargflargler that just describes it as "Flargles the narg" provides zero additional information to you.

I want a linter against this. I have a hatred for those kinds of docs, they take up screen space, its worse than nothing.

then how would you descirbe a nargfargler?

dont say.. boop?!

God I hate this so much when I google some unknown word and it's just: "Nargflargler: When someone narg flargles something"

Reply on news.ycombinator.com