Hacker News Reader

Comment by zija | Hacker News Reader

I don't understand why the dotnet team doesn't invest more resources and time into tools: doctests and documentation generation, better and faster unit tests that I can write next to the actual code, easy access to the source code, no need to decompile a Dll to see it after pressing F12, a central place for packages and documentation like in pkg.go.dev or docs.rs . Most packages in nuget have no documentation at all, or only in readme format on GitHub, or a short Wiki on this page. Other environments like Rust, Golang, Java, Python are light years ahead when it comes to these aspects.

View on HN

A part of me jokes that Micro$oft only invested in OpenAI because it's the only sensible way to browse .NET/Nuget package(s) documentation. The other part knows it's dreadfully true.

Small F# community have https://fsprojects.github.io/FSharp.Formatting/ that is a lot better than docfx, it has markdown support, notebook suport, script output embedding.

C# has nothing like that, xml comments and raw documentation that has no value

In all their docs they now have links directly to the source for the method you are looking at, for example https://learn.microsoft.com/en-us/dotnet/api/system.string.s...

As for source for nuget packages, it's easy to enable source link to make that happen too, it's just that this is all pretty new so not every package is doing it.

I agree with you, but I think this is most likely due to how relatively new open source C# is. I'd hazard that most C# being written is still done by enterprises/companies as closed source. I feel this will improve over time, as long as Microsoft continues down the road of being open, and doesn't pull back what they've been doing in the last few recent years.

Some of these features are provided by tools like Resharper, and I wonder if there isn't some kind of agreement (whether written or unspoken) where they don't step on each other's toes. To be honest, most documentation I have seen written in C# projects still makes me reach for the source code due to poor quality. Having lots of autocompleted tooling doesn't help when it comes to reading, only writing, in my experience.

Very true! My first non-work opensource C# project is from 2020 and that seemed strange at the time

https://github.com/unfrl/dug

This is awesome, because most CLI tools for this don't seem to work anymore (at least in my experience). I need to talk to my employer, but I'd like to open source some work I've done for generating static redirects/rewrites in IIS format (still able to be used by open source .NET), as well as a tool that will take those redirects and visit the original URL, then check that a 301 redirect occurred, with the Location header set to the appropriate new URL. I work with a digital marketing agency, and we do a lot of SEO work, including making sure old URLs match up with new URLs. I got pulled into the creation of 301 redirects, so built tooling to take care of it for me.

Sandcastle Helper File Builder has been around forever and started as an internal MS project IIRC, but for some reason few libraries use it.

https://github.com/EWSoftware/SHFB

I used to use this quite a bit after it was introduced, but CHM files are a bit unwieldy for documentation, at least for myself. Having integrated search is nice, but the windowed interface, and being tied to Windows (AFAIK, maybe there are readers for other operating systems) I believe will keep this project from being used. I always found it to be decent for more advanced developers, but felt there was something missing for more junior developers that needed documentation.

I haven't used it in 4-5 years but at the time we were generating html docs with it. IIRC it supports several other output formats.

Here’s a way to write tests next to the code: https://clipperhouse.com/go-test-csharp/

(Whether I recommend it, not sure! I did it and then undid it, with suspicion that tests were taking longer due to, perhaps, worse caching of build artifacts.)

Reply on news.ycombinator.com