9 ms·
That makes me wonder: if I fix something, if I set up Chesterton's fence, how can I make it a bit more obvious why I'm putting that fence there for the benefit
by ben509 8y ago
That makes me wonder: if I fix something, if I set up Chesterton's fence, how can I make it a bit more obvious why I'm putting that fence there for the benefit of future us?
- MaxBarraclough 8y agoThe usual code-comments/self-documenting code/git commit descriptions, no? If a long-form explanation is justified, wikis are cheap. I see no excuse for leaving the reader to guess at what on Earth you were thinking. Implementing a wacky solution is sometimes a necessary evil. Incomprehensibility isn't.
- gknoy 8y agoAt the risk of sounding snarky, I feel like a block of code comments explaining the naiive approach that was rejected, as well as the particular edge cases that this is handling which the simpler generalized case doesn't handle, would help a lot for that. I realize that as developers we often glaze over the comments (my editor even shows them as low contrast grey), but docstrings and code comments can be tremendously valuable when trying to understand why something needs to do things a particular way.
- hinkley 8y agoI am downright militant about people not relocating code and breaking the commit history. When I see WTF code, I want to know what story it was associated with so I know why the fences were erected. Sometimes they are right and I need a complex solution. Sometimes they were accomplishing something the hard way and there was an easier spot to achieve the goal. Basically I am fixing two bugs. The old one again, and the new one.