> read API docs for anything I’m unfamiliar with
One of the differences i've noticed between myself and some of the junior devs i've worked with. I would usually use the official docs as my first resource, and they would use stack overflow instead.
One of the differences i've noticed between myself and some of the junior devs i've worked with. I would usually use the official docs as my first resource, and they would use stack overflow instead.
I'm impatient and Stack overflow can often give me an easy solution. But just as often, it can't and I will spend 30 minutes unproductively trying things with little progress.
As I become a better developer I become more inclined to spend 30 minutes with the documentation instead.
I know it'll be worth it in the long run, but it feels like I'm wasting time because "I'm not doing anything" - I'm not committing any changes while my coworkers are busy adding new features.
Of course most of interesting problems are not described in documentation.
I would use whichever googles first and most relevant results are. Also what the issue is matters.
I don't always go to MDN for javascript issues.
But if I want to know why something is the way it is, I will.
The people who made the mistake in the OP probably did exactly that.
This is not granted, but it happens a lot. Although if the docs are good, you should definitely expect to find good information about deprecation notices there, too! But it's not at all uncommon for conversations about code, on StackOverflow or wherever else, to include the footnotes about what is different and what version changed it.
- open source libraries - online casual browser games - development/staging environment counterpart to a .com
Take their Azure Python API, which is clearly translated directly from C#: There's a number of functions, which according to the documentation takes a string as an input. The thing is that it won't actually take a string, it will take three or four predefined strings. Everything else will yield no result. The only thing Microsoft doesn't care to put in the documentation is which strings are actually valid and what result you can expect from them.
i was trying to do some work with their crm solution it took me a literal week to find out how to do simple oauth -- mostly because 99% of the documentation only had .NET examples using their own framework!
No, I don't want to do a full reload for every overload of a method. Yes, I might want to see where these extension methods are popping up from, out of nowhere.
Sometimes there is just no usable documentation for certain things at all. I've even seen documentation for certain Azure things where it just directs you to Stack Overflow!
The documentation is definitely there, but finding it can be a curse. The search is worse than Google, the site is surprisingly slow for a bunch of static text, and the ability to discover something when you don't know the right search terms is poor because Microsoft name everything in the most generic way possible.
The content is bad: Quick, is System.DateTime[0] timezone-aware? The examples also use (the harmful and bug-prone) DateTime.Now 5 times, while DateTime.UtcNow is only mentioned once, as a minor aside.
The structure is bad: Is something part of "Core", "Framework", "Standard", or "Platform Extensions"? It's particularly ridiculous that trying to switch from Core to Platform Extensions while you're viewing a Core class (such as System.DateTime[0]), you'll get kicked over to.. Framework.
The layout is bad: Look at System.DateTime's list of constructors[1]. It takes up a whole screenful to say what Python's datetime.datetime constructor[2] paragraph says in three lines.
The design is bad: Compare the method listing of .NET's IDictionary[3] to Scala's Map[4], or Rust's HashMap[5]. Which one makes the type signatures the easiest to parse? Which one helps you get where you want to the fastest?
(Hint: For me, at least, not the one that insists on making everything a uniform shade of baby blue.)
[0]: https://docs.microsoft.com/en-us/dotnet/api/system.datetime?...
[1]: https://docs.microsoft.com/en-us/dotnet/api/system.datetime?...
[2]: https://docs.python.org/3/library/datetime.html?highlight=da...
[3]: https://docs.microsoft.com/en-us/dotnet/api/system.collectio...
[4]: https://www.scala-lang.org/api/current/scala/collection/immu...
[5]: https://doc.rust-lang.org/stable/std/collections/struct.Hash...
For a similar example, Scala's old collections library had a ton of machinery to ensure that `map` and co. would specialize correctly.[0] But the user never sees that, because they added a mechanism called "use cases", that allow you to override the signature shown in the docs with a simpler one.[1]
[0]: https://github.com/scala/scala/blob/v2.12.10/src/library/sca...
[1]: https://www.scala-lang.org/api/2.12.10/scala/collection/immu...
Namely, "some dude's gist or blogpost [or stack overflow answer]" not getting updated. Not just that they didn't but that they couldn't.
Unsurprisingly, which you should rely on depends heavily on context. It takes experience and patience to figure out which one is correct based on circumstances.
IDE type search and doc comments are much more likely to be useful.