4 ms·
I do think it's a bit telling that we have a lot of automated software that exists to help us style our code, but there doesn't seem to be nearly as much invest
by seangrogg 5y ago
I do think it's a bit telling that we have a lot of automated software that exists to help us style our code, but there doesn't seem to be nearly as much investment in documenting code.
Simple things like a linter that yells at you if a class has an undocumented method would probably at least be a step in the right direction. People may complain that it would lead to overdocumentation but I'd argue that it's probably better than underdocumentation.
Even something as simple as providing a warning when there appears to be an long code block without documentation would probably be a step in a decent direction. What seems trivial and obvious today likely will not in a matter of weeks - and it generally just gets worse from there.
- the_duke 5y agoIn Rust you can just add `#![deny(missing_docs)]` to your code and compilation will fail if you have any undocumented items. Of course that can lead to developers just adding a single line comment with the name of the type ... but it's still a nice feature.
- seangrogg 5y agoThat's actually super cool; I wish I had more reasons to reach for Rust on a regular basis but this is definitely something I'll keep in mind should I ever get the opportunity to use Rust in any capacity.
- HeyLaughingBoy 5y agoVisual Studio nags you if public methods and properties aren't documented. It's not a panacea, in fact it's easy to work around but at least they're trying. IME, the only thing that works is to attack it from a Project level: make usable documentation (needs a review before being signed off) a deliverable or the project isn't done.