↩ go back to index

comparing language documentation

february 18, 2021

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.

nytpu’s criterion for determining whether a language is worth it to use or not and also a measure of whether the language designers care about the developers that use it

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.

looking at languages

rust

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‽)

c

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!

go

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.

python

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.

conclusions

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.

↩ go back to index

like this post!

view likes and comments

contact: alex@nytpu.com

backlinks

-- © 2021 nytpu - CC-BY-SA-4.0

Proxied content from gemini://nytpu.com/gemlog/2021-02-18.gmi

Gemini request details:

Original URL
gemini://nytpu.com/gemlog/2021-02-18.gmi
Status code
Success
Meta
text/gemini; lang=en
Proxied by
kineto

Be advised that no attempt was made to verify the remote SSL certificate.