theanti9-com.pages.dev Open in urlscan Pro
188.114.96.3  Public Scan

Form analysis
0 forms found in the DOM

Text Content

DEFINITELY REAL SOFTWARE ENGINEERING




LATEST

Required Documentation - Even Just For Myself
Sun Jan 01 2023

--------------------------------------------------------------------------------

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.



©2022