5 ms·

I work half and half pretty much maintaining the same app in both iOS and Android. Since the introduction of Swift, the Apple docs have become much terser (it's

I work half and half pretty much maintaining the same app in both iOS and Android. Since the introduction of Swift, the Apple docs have become much terser (it's like Jony Ives slimness fettish got a hold of them). Even with that, they're better (by far) than what I find with the Android docs. The Android docs "explain" very little.

iainmerrick 7y ago
Android suffers a lot from quantity over quality. Classes are usually documented, but usually for a function like “setReturnVectorFlag” it’s just sets the return vector flag. Edit to add: I also work on both platforms, and I’d say iOS (along with MacOS) is usually easier to work with because the design tends to be sane and the names are fairly descriptive; whereas Android has a lot of weird and questionable design decisions so it’s harder to guess how things really work. On the upside for Android, it’s often possible to just read the source code (at least for the core OS). I think the docs are about equally bad overall.
- andybak 7y ago
  > usually for a function like “setReturnVectorFlag” it’s just sets the return vector flag. Ah - the "repeat the method names with spaces in it" style of documentation. This is merely an exaggerated form of a trap that the majority of documentation falls into to some degree - documenting the "what" but neglecting the "why" or "how". It tells you the bit you can easily work out by intuition, reading the source or using your IDE's features. And it leaves out the really important parts: "how should I use this method?" and "why would I need to?" Method based documentation also has problems explaining how API calls are used in concert. Understanding each method in isolation something leaves huge gaps in understanding how they are to be used together. And no - you can't plug the gaps with lazy video tutorials.
  - oefrha 7y ago
    > Ah - the "repeat the method names with spaces in it" style of documentation. That's usually a symptom of aggressive linters enforcing the rule that every single public method must be documented. Programmers then produce useless "documentation" to shut the linters up. Utter waste of disk space.
    - kbenson 7y ago
      I can see that as possible, and I can also see how it might very negatively impact a documentation drive on accident. One of those things that sounds good, and could be beneficial, but when enacted without strong guidance just ends up combining with culture or human nature to make things worse. E.g. a rule that says there must be documentation, but without standards and enough review to make sure that it's good documentation. Stats show things getting better, but that's because we always drift towards optimizing what we measure, which is not always the same what we actually want.

iainmerrick 7y ago

Android suffers a lot from quantity over quality. Classes are usually documented, but usually for a function like “setReturnVectorFlag” it’s just sets the return vector flag. Edit to add: I also work on both platforms, and I’d say iOS (along with MacOS) is usually easier to work with because the design tends to be sane and the names are fairly descriptive; whereas Android has a lot of weird and questionable design decisions so it’s harder to guess how things really work. On the upside for Android, it’s often possible to just read the source code (at least for the core OS). I think the docs are about equally bad overall.

andybak 7y ago
> usually for a function like “setReturnVectorFlag” it’s just sets the return vector flag. Ah - the "repeat the method names with spaces in it" style of documentation. This is merely an exaggerated form of a trap that the majority of documentation falls into to some degree - documenting the "what" but neglecting the "why" or "how". It tells you the bit you can easily work out by intuition, reading the source or using your IDE's features. And it leaves out the really important parts: "how should I use this method?" and "why would I need to?" Method based documentation also has problems explaining how API calls are used in concert. Understanding each method in isolation something leaves huge gaps in understanding how they are to be used together. And no - you can't plug the gaps with lazy video tutorials.
- oefrha 7y ago
  > Ah - the "repeat the method names with spaces in it" style of documentation. That's usually a symptom of aggressive linters enforcing the rule that every single public method must be documented. Programmers then produce useless "documentation" to shut the linters up. Utter waste of disk space.
  - kbenson 7y ago
    I can see that as possible, and I can also see how it might very negatively impact a documentation drive on accident. One of those things that sounds good, and could be beneficial, but when enacted without strong guidance just ends up combining with culture or human nature to make things worse. E.g. a rule that says there must be documentation, but without standards and enough review to make sure that it's good documentation. Stats show things getting better, but that's because we always drift towards optimizing what we measure, which is not always the same what we actually want.