3 ms·

I guess people's expectations might have been lower? MSDN sucks along every axis I can imagine. The content is bad: Quick, is System.DateTime[0] timezone-aware

I guess people's expectations might have been lower? MSDN sucks along every axis I can imagine. 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?view=netcore-3.1 https://docs.microsoft.com/en-us/dotnet/api/system.datetime?... [1]: https://docs.microsoft.com/en-us/dotnet/api/system.datetime?view=netcore-3.1#constructors https://docs.microsoft.com/en-us/dotnet/api/system.datetime?... [2]: https://docs.python.org/3/library/datetime.html?highlight=datetime#datetime.datetime https://docs.python.org/3/library/datetime.html?highlight=da... [3]: https://docs.microsoft.com/en-us/dotnet/api/system.collections.generic.dictionary-2?view=netcore-2.0 https://docs.microsoft.com/en-us/dotnet/api/system.collectio... [4]: https://www.scala-lang.org/api/current/scala/collection/immutable/Map.html https://www.scala-lang.org/api/current/scala/collection/immu... [5]: https://doc.rust-lang.org/stable/std/collections/struct.HashMap.html https://doc.rust-lang.org/stable/std/collections/struct.Hash...

qidydl 7y ago
Python's datetime appears to have one constructor with several optional parameters, whereas .NET's System.DateTime has several separate constructors each taking a different set of parameters. The MSDN documentation is accurate and correct; your critique applies to the underlying code (which is built to be backwards-compatible to .NET 1.0, which I don't think even supported optional arguments).
- Nullabillity 7y ago
  The signatures that are useful when developing the library might be more complex than the ones that the library consumer would be interested in. This isn't much of an excuse when you also maintain the documentation tools. 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/scala/collection/immutable/List.scala#L283-L299 https://github.com/scala/scala/blob/v2.12.10/src/library/sca... [1]: https://www.scala-lang.org/api/2.12.10/scala/collection/immutable/List.html#map[B](f:A=%3EB):List[B] https://www.scala-lang.org/api/2.12.10/scala/collection/immu...

qidydl 7y ago

Python's datetime appears to have one constructor with several optional parameters, whereas .NET's System.DateTime has several separate constructors each taking a different set of parameters. The MSDN documentation is accurate and correct; your critique applies to the underlying code (which is built to be backwards-compatible to .NET 1.0, which I don't think even supported optional arguments).

Nullabillity 7y ago
The signatures that are useful when developing the library might be more complex than the ones that the library consumer would be interested in. This isn't much of an excuse when you also maintain the documentation tools. 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/scala/collection/immutable/List.scala#L283-L299 https://github.com/scala/scala/blob/v2.12.10/src/library/sca... [1]: https://www.scala-lang.org/api/2.12.10/scala/collection/immutable/List.html#map[B](f:A=%3EB):List[B] https://www.scala-lang.org/api/2.12.10/scala/collection/immu...