Comment the Why *and* the What
I’d say I’m 10-20% of the way towards a presentable early access. So yeah, probably not going to have something shareable by the end of this month, which I’m sure absolutely everybody saw coming. I apparently forgot to factor “having a social life again” into my schedule.
One positive thing: I saw that people really liked the last newsletter about informing software design with logic. That fills me with confidence that this book is needed.
People say “comment the why, not the what”, the idea being that the code should be self-documenting and the comments should only be a last resort for explaining stuff. Comments can get out of sync, but the code is always the code, so there’s no need for unnecessary redundancy.
I disagree: No matter how self-documenting the code is, comments help a lot with understanding stuff. Whenever I go back to an old project, I find the comments far more useful to reorient myself than my code or my tests. Here are some cases where adding the “what” is really helpful.
