Definitely Real Software Engineering

I've been working on hobby game engine on a semi-regular basis in my spare time. It's a learning project, more than anything else, written in Rust.

While toying around this week, I decided to disallow missing documentation, project-wide. All it takes is one little line in lib.rs:

#![deny(missing_docs)]

This means I can't even compile and run tests without the build failing. All public structs, traits, modules, fields, etc, must be documented.

As it turns out, this is, at times, annoying. But I'm finding that it forces me to write both better code and documentation. It requires me to think just a little bit more ahead. Because I have to document as I write. Or at the very least, document after I've forgotten for a while and the compiler coldly tells me I'm an idiot. And on multiple occasions already this has caused me to find bugs, patterns that don't make sense, extraneous code, and many opportunities for improvements or optimizations. It also provides a push to think about what needs to be public and what doesn't and nudges me toward cleaner, more thoughtful library APIs. Because the private stuff doesn't need to be documented (though I find I often add it anyway).

I'm pretty confident that no one other than me is using this library at the moment (and they probably shouldn't), but to comment and document the code under the assumption that someone is - or will - has quickly proven a forcing function in writing better, cleaner, more thoughtful code.