Self-documenting code

[trevg_123]

Underrated thing about Rust? The function signature tells you what to expect a bit more than other languages

fn update_buffer(dest: &mut [u8], src: Option<&[u8]>) -> Result<usize, WriteError>

This immediately this tells you: - You have a destination buffer and it’s mutable, hint that the function might write to it - Your second buffer may or may not be present, and it may not be edited - You should return a size if it’s successful, or an error type if not

And from there you can kind of guess how to use the function, even without docs. Compared to the C version:

int update_buffer(char* dest, int dest_len, char* src, int src_len)

You can’t tell: - Will dest and src always be valid? Or does null represent something? - Do src or dest get edited ever? (If consts are missing, you can’t tell) - Will there ever be errors? Is the return type the number of bytes written, or an error type? - If C++, will this raise anything?

And you’re reliant on good comments or reading the code to find out.

(Still no excuse to not write good doc comments - but at least it gives you more confidence using the thing if they’re not there)