|
|
|
|
|
|
by rkagerer
1059 days ago
|
|
|
Part of writing and maintaining good code is maintaining useful documentation (such as comments) expressing clear rationale and intent. Simple stuff can be elegantly implicit, and modern languages are getting better at capturing more of this in syntax and eliminating common footguns. But more complex systems tend to benefit from explicit explanation or even external design documents (like diagrams). A fix that doesn't keep those current isn't a completed fix. When I come in on a consulting basis I often have to help developers unwind the unintended effects of years of patches before we can safely make seemingly-simple changes. It's analysis-intensive, and like an archaeologist any artifacts I can dig up that you've left behind providing clues to what was in your head at the time can be helpful. In some cases where a set of functions is super critical we've made it part of the culture every time altered code is checked in to perform a walkthrough analysis to uncover any fresh unintended side-effects, ensure adherence to design requirements and discover and spotlight non-obvious relationships. The key is to turn the unintended or non-obvious into explicit. Sounds painful but in practice due to the high risk attached to getting that portion of code wrong the developers actually love that time for this is worked into the project schedules - it helps them build confidence the alteration is correct and safe. I wish it were easier to impress the importance of this on inexperienced developers without them having to go through the hell of maintaining code in an environment where it was lacking. It's a skill and art to keep the appropriate level of conciseness to avoid the documentation (no matter which form it takes) becoming too verbose or unwieldy to be helpful. |
|
|
this is also why tests are so important. if you want to remove something, you have to think twice... once for the original code and once to fix the broken tests.