-- Leo's gemini proxy
-- Connecting to nytpu.com:1965...
-- Connected
-- Sending request
-- Meta line: 20 text/gemini;lang=en-US;charset=utf-8
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:
Most/all documentation is available offline (officially, something like zeal doesn’t count)
Most/all documentation is available without a web browser
If it does require a web browser, it is viewable in a terminal browser like lynx
The documentation is well-organized and easily browsable
Bonus points if third party libraries can easily add their documentation to the offline documentation source
The language has a clear, consistent specification that anyone can read
The language has a formal specification at all
If there is no specification, the reference implementation is easily readable and understandable
Bonus points for the reference implementation being hackable
The standard library (or equivalent) has complete documentation
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:
Most/all documentation is available offline (officially, something like zeal doesn’t count)
Yes, with rustdoc. It’s mostly for generating documentation for local projects, but I believe it has a copy of the std docs too.
Most/all documentation is available without a web browser
Nope.
If it does require a web browser, it is viewable in a terminal browser like lynx
Absolutely not.
The documentation is well-organized and easily browsable
I don’t use it regularly (obviously), but clicking around the std docs it seems incoherent sometimes.
Bonus points if third party libraries can easily add their documentation to the offline documentation source
Yes, I believe the aforementioned rustdoc can generate documentation for installed libraries^Wcrates.
The language has a clear, consistent specification that anyone can read
No.
The language has a formal specification at all
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//////!!!!!!!!!!!!!!!!!!!!!!!!!
If there is no specification, the reference implementation is easily readable and understandable
Nope, >350,000 lines of difficult to understand code.
Bonus points for the reference implementation being hackable
Absolutely not, even compiling it yourself is a bitch.
The standard library (or equivalent) has complete documentation
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‽)
Most/all documentation is available offline (officially, something like zeal doesn’t count)
Yes, man pages.
Most/all documentation is available without a web browser
Yes.
If it does require a web browser, it is viewable in a terminal browser like lynx
N/A.
The documentation is well-organized and easily browsable
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.
Bonus points if third party libraries can easily add their documentation to the offline documentation source
Yes, it’s trivial to add new man pages.
The language has a clear, consistent specification that anyone can read
No, the standard isn’t particularly useful to anyone other than compiler devs.
The language has a formal specification at all
Yep!
If there is no specification, the reference implementation is easily readable and understandable
No official reference implementation. N/A.
Bonus points for the reference implementation being hackable
Not the reference implementation, but the major compilers and libc’s are not easily hackable.
The standard library (or equivalent) has complete documentation
Yes, man pages.
So C meets 7/10, it passes!
Most/all documentation is available offline (officially, something like zeal doesn’t count)
Yes, via godoc.
Most/all documentation is available without a web browser
Yes, `godoc` is web-only but `go doc [QUERY]` is in the terminal!
If it does require a web browser, it is viewable in a terminal browser like lynx
Absolutely! Works great!
The documentation is well-organized and easily browsable
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.
Bonus points if third party libraries can easily add their documentation to the offline documentation source
As a bonus new modules are automatically added to godoc as you download them!
The language has a clear, consistent specification that anyone can read
Yep, it’s great!
The language has a formal specification at all
Yep!
If there is no specification, the reference implementation is easily readable and understandable
Very big, not really.
Bonus points for the reference implementation being hackable
Ehhh, not really.
The standard library (or equivalent) has complete documentation
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.
Most/all documentation is available offline (officially, something like zeal doesn’t count)
Yes, but has to be manually downloaded from the python website.
Most/all documentation is available without a web browser
Yes, but the non-web versions are raw html→XXX conversions so they’re pretty inferior. 0.5 points here.
If it does require a web browser, it is viewable in a terminal browser like lynx
Yes, it’s /usable/ but not optimal.
The documentation is well-organized and easily browsable
Yeah, I suppose so.
Bonus points if third party libraries can easily add their documentation to the offline documentation source
No, not at all. There are third party things like sphinx but there’s not one source for docs, they’re spread all over.
The language has a clear, consistent specification that anyone can read
Yep.
The language has a formal specification at all
Yep.
If there is no specification, the reference implementation is easily readable and understandable
Not really, if you don’t know cpython then you’re pretty SOL.
Bonus points for the reference implementation being hackable
Nope.
The standard library (or equivalent) has complete documentation
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.
⁂
-- Response ended
-- Page fetched on Wed Apr 24 18:00:38 2024
