3 ms·
Okay but that's kind of a different problem isn't it? If people can't be bothered to comment their code properly I doubt they're going to write high quality LaT
by simias 8y ago
Okay but that's kind of a different problem isn't it? If people can't be bothered to comment their code properly I doubt they're going to write high quality LaTeX documentation on the side.
I find that Rust deals with that mostly well, the doc format is part of the language, the documentation generation part of the toolchain. You can even validate example code from the comments. You can enable warnings for missing documentation on methods. In my experience documentation for Rust crate is generally at least okay-ish, it generally saves me a trip into the code itself. That being said Rust prototypes are also a lot more expressive than their C counterparts (no questions about "should I free that pointer?") so that probably helps as well.
- nottorp 8y agoMy point is that the harder you make it for people to comment their code, the less useful comments you'll get. Freeform text (where you can even whip up a ghetto table or graph with a fixed size font in a few minutes) gives you the best chance of meaningful comments.
- simias 8y agoI'm not convinced, I don't find the Rust format particularly hard to grok, it's Markdown so it looks mostly fine when viewed as plaintext. A Markdown table is pretty ghetto but on top of that it'll display nicely in the generated HTML. Also if you really want to do ascii art you can always use ``` to escape everything: https://github.com/simias/pars/blob/ce820b5af0be3091d47104cf2bcd4aa537c6d11d/pars-lexer/src/nfa.rs#L201-L211 https://github.com/simias/pars/blob/ce820b5af0be3091d47104cf... I guess it does add a little bit of friction but if somebody tells me they don't write docstrings because they don't want to bother with the Markdown syntax I'd reply I'm going to assume that they're just looking for excuses at this point.