2 ms·
I try very hard to avoid writing clever code. Instead, I strive for maximum clarity and simplicity. But on rare occasions I do have to write something clever,
by pmoriarty 8y ago
I try very hard to avoid writing clever code. Instead, I strive for maximum clarity and simplicity. But on rare occasions I do have to write something clever, because the simple and clear thing would either be less efficient, or much much longer, or involve lots of boiler plate code reuse.
In those cases I may have to explain not only why I wrote the clever part, but also how it works, because it might not be immediately obvious unless the reader digs really deep in to the code to figure it out. I'd rather save them (or me at a later date) the trouble.
Yes, this risks having the documentation drift away from the code if I ever change the code (or if I make a mistake in the documentation), but it's a risk I'm willing to take in small doses.