5 ms·
I feel like a step towards a solution to this problem (which I likewise observe), is to document these idiosyncrasies in the code. My rule of thumb is that when
by gen220 7y ago
I feel like a step towards a solution to this problem (which I likewise observe), is to document these idiosyncrasies in the code. My rule of thumb is that when I write or read weird code that's necessarily weird (to avoid idiosyncrasies in downstream/upstream systems), I try to add a very concise clarifying comment that acknowledges the code as weird, and points in the direction of both the problem we're avoiding and some potential solutions to make the code less weird in the future.
For example, when reading an old codebase, if I invest 20 minutes in determining why the code differs from the documentation, I add a comment saying `NOTE(gen220): the code does not match the comment. The reason appears to be X. We might resolve this with Y or Z`. That, or update one of either the code or the comment, whichever makes the most sense in the situation.
That way, a new team member (or myself, but 2 years older) won't have to stumble in the same places, and are empowered to take a stab at fixing the problem, which has been documented for them.
Personally, when my idiosyncrasies are so-documented, I feel much safer handing things off.
- TeMPOraL 7y agoI agree with your proposed step forward. Myself, recently I've been more often producing fresh code than working on someone else's, so I ended up aggressively documenting design decisions in code - most of them in top-level file comments, and the more local/tactical decisions within the scope they affect. I try to do that simultaneously with writing the code, because unless I write things down immediately, there's a good chance I'll never go back to put them in.
- achenatx 7y agoI do this and I also initial and date the comment so people have some idea where in the timeline it was introduced and who to talk to about it.