6 ms·
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 nam
by imgabe 1y ago
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.
- wouldbecouldbe 1y agoOr with Xcode, go to fargler settings click on narg screen. Took a year just to figure out most setting screens
- whstl 1y ago> 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.
- Aaargh20318 1y agoRelated 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).
- bonoboTP 1y agoIn 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.
- CaptainOfCoit 1y agoThat'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.
- clickety_clack 1y agoIf 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.
- tetha 1y agoThis 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.
- account42 1y agoBetter 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".
- 1718627440 1y agoBut that's what the actual hungarian notation was about: decoding the type of thing it represents not the data type used.
- godelski 1y agoThis 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
- zestyping 1y agoCode can show you HOW something is done. Only documentation can explain WHY it is done that way.
- account42 1y agoThis 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.
- godelski 1y agoYou'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
- multifasciatus 1y agoAVMetadataKeySpace A structure that defines a metadata key space. source: https://developer.apple.com/documentation/avfoundation/avmetadatakeyspace https://developer.apple.com/documentation/avfoundation/avmet...
- fingerlocks 1y agoThat’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/retrieving-media-metadata https://developer.apple.com/documentation/avfoundation/retri...
- shakna 1y agostruct AVMetadataKeySpace - a unique unit representing each of the metadata key spaces supported by AVFoundation.
- fingerlocks 1y ago? 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.
- shakna 1y agoThe 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.
- fingerlocks 1y agoBecause 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.
- rmunn 1y agoThis 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).
- zahlman 1y ago> 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.
- tartoran 1y agoBut that could be linked up rather than have you fumble through to find them.
- godelski 1y agoThis 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
- wang_li 1y agoThe 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?language=objc 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.
- account42 1y agoNo, 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.
- hayleox 1y agoNot quite what you're talking about but this Apple doc page has always amused me: https://developer.apple.com/documentation/contacts/cnlabelcontactrelationyoungercousinmotherssistersson 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.
- peterfirefly 1y agoThere are indeed languages that don't have the word "cousin" -- or "uncle" or "aunt".
- alt227 1y agoBut I would bet that those variable labels are never translated into other languages.
- account42 1y agoPresumably 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.
- delecti 1y agoAnd conversely, there are languages with different words for "father's sister" and "mother's sister", and for male vs female cousins, etc.
- peterfirefly 1y agoAnd 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.
- sim7c00 1y agothen how would you descirbe a nargfargler? dont say.. boop?!
- Eric_WVGG 1y agoApple 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.
- billforsternz 1y agoOne 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.
- astrange 1y agoThe 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
- billforsternz 1y agoI 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.
- 1718627440 1y agoIts a standard thing to do in C. You generally use a prefix of 2-4 characters from your project name.
- testing22321 1y agoTriangle theTriangle = new Triangle() Lives rent free in my brain.
- deleted 1y ago[deleted]
- stuaxo 1y agoI want a linter against this. I have a hatred for those kinds of docs, they take up screen space, its worse than nothing.
- sunaookami 1y agoGod I hate this so much when I google some unknown word and it's just: "Nargflargler: When someone narg flargles something"