đŸ Archived View for nytpu.com âș gemlog âș 2021-02-18.gmi captured on 2024-03-21 at 15:29:35. Gemini links have been rewritten to link to archived content
âŹ ïž Previous capture (2022-03-01)
âĄïž Next capture (2024-05-10)
-=-=-=-=-=-=-
The most important thing and yet the most undervalued thing for programming languages (and software in general) is clear, consistent documentation. If a language doesnât set a good example for good documentation, then it seems that the developers in that language follow its example. This is a short post, but weâre going to compare a few programming languages against my preferences for documentation.
A languageâs documentation should meet half of these ten requirements:
Some are more important than others, but weâre just going to go with 5/10 to make it easy to judge. N/Aâs count as a point because if something like a browser isnât required at all the point for being viewable in lynx is moot, so it gets both.
Ordinarily I wouldnât even give rust the time of day, but it does so abysmally I had to share:
Yes, with rustdoc. Itâs mostly for generating documentation for local projects, but I believe it has a copy of the std docs too.
Nope.
Absolutely not.
(282.5kib) really wonderful rust, really readable
I donât use it regularly (obviously), but clicking around the std docs it seems incoherent sometimes.
Yes, I believe the aforementioned rustdoc can generate documentation for installed libraries^Wcrates.
No.
Nope! Something silly like a specification is for the boomer developers, weâre cool and hip! We write code and change functionality as we please! Who needs a stable language when you have //////memory safety//////!!!!!!!!!!!!!!!!!!!!!!!!!
Nope, >350,000 lines of difficult to understand code.
Absolutely not, even compiling it yourself is a bitch.
Yes, via rustdoc.
So, rust meets 3/10, it fails by any standard. Disappointed, but not surprised. The only decent part is offline rustdoc but even thatâs just directly ripped off from godoc, but shittier. (you have to write markdown code comments✠WTFâœ)
Yes, man pages.
Yes.
N/A.
Ehhh, not really. If you know what function youâre looking for man pages are good, but if you donât know what header or function to use it can be hard.
Yes, itâs trivial to add new man pages.
No, the standard isnât particularly useful to anyone other than compiler devs.
Yep!
No official reference implementation. N/A.
Not the reference implementation, but the major compilers and libcâs are not easily hackable.
Yes, man pages.
So C meets 7/10, it passes!
Yes, via godoc.
Yes, `godoc` is web-only but `go doc [QUERY]` is in the terminal!
Absolutely! Works great!
Yep, organized nicely and easy to find the function for what you want to do even if you donât know what/where it is exactly.
As a bonus new modules are automatically added to godoc as you download them!
Yep, itâs great!
Yep!
Very big, not really.
Ehhh, not really.
Yep, via godoc.
So Go passes with 8/10, as a C-inspired language it makes sense that itâd be Câs equal, but IMO Goâs documentation is better than Câs so the extra point makes sense.
Yes, but has to be manually downloaded from the python website.
Yes, but the non-web versions are raw htmlâXXX conversions so theyâre pretty inferior. 0.5 points here.
Yes, itâs /usable/ but not optimal.
Yeah, I suppose so.
No, not at all. There are third party things like sphinx but thereâs not one source for docs, theyâre spread all over.
Yep.
Yep.
Not really, if you donât know cpython then youâre pretty SOL.
Nope.
Yep, in the aforementioned documentation.
So python gets 6.5/10, better than I was expecting.
I was going to go over more languages but I got lazy. I donât even know what point Iâm trying to make other than that documentation is important, but there is one major takeaway from this: rust is a shitty language with shitty designers and a shitty community. Thatâs for a variety of reasons, not just this documentation thing, this is a symptom, not a cause, of rustâs problems.
My post meant to emphasize good documentation turned into a rust sucks post, yay! I need to make a real rust sucks post sometime soon, itâs been coming out on fedi more than Iâd like.
â
