3 ms·

We have a rule that if you have to leave shit code as it is for a serious reason (time constraints, shifting requirements) you must leave a TODO in the code whi

by kgeist 5y ago

We have a rule that if you have to leave shit code as it is for a serious reason (time constraints, shifting requirements) you must leave a TODO in the code which poins to a freshly created issue in the tracker which explains what's wrong with the code and how it can be fixed. The ideal is that these issues eventually get fixed, which is often not the case (new features are prioritized over tech debt etc.), but at least new devs will immediately see that it's a known problem and that there're known solutions.

KronisLV 5y ago
> We have a rule that if you have to leave shit code as it is for a serious reason (time constraints, shifting requirements) you must leave a TODO in the code which poins to a freshly created issue in the tracker which explains what's wrong with the code and how it can be fixed. This seems like a really sane thing to do! In addition, if you want to keep track of the commits and the context behind them, i've found that merge/pull request descriptions are also really nice for this! Back when i had to struggle with an Eldritch DB schema that someone wrote and had to patch in new functionality, i ended up painstakingly mapping out how it corresponded to the business concepts/objects (which was pretty loosely) and threw that diagram into the merge request, because sadly otherwise the schema still wasn't all that clear... ...just to have that very same diagram save my hide when i had to go back to it months later to update some of the code, which necessitated rediscovering how everything works. Now, whether things belong in the issue tracker or somewhere that's more close to the code repo is probably just a cultural question, but i'd say the main thing is to have some place to store information like that.
- physicles 5y ago
  Staying close to the code where possible always wins, I think. One code base I worked in had a particularly complex state machine, and right above its main function was a giant ascii art diagram of said state machine. It was perfect documentation.
  - KronisLV 5y ago
    Oh, definitely! I've had similarly positive experiences with temporal algebra - having some simple explanatory graphics of how two time spans would overlap is really nice!

by kgeist 5y ago

KronisLV 5y ago

> We have a rule that if you have to leave shit code as it is for a serious reason (time constraints, shifting requirements) you must leave a TODO in the code which poins to a freshly created issue in the tracker which explains what's wrong with the code and how it can be fixed. This seems like a really sane thing to do! In addition, if you want to keep track of the commits and the context behind them, i've found that merge/pull request descriptions are also really nice for this! Back when i had to struggle with an Eldritch DB schema that someone wrote and had to patch in new functionality, i ended up painstakingly mapping out how it corresponded to the business concepts/objects (which was pretty loosely) and threw that diagram into the merge request, because sadly otherwise the schema still wasn't all that clear... ...just to have that very same diagram save my hide when i had to go back to it months later to update some of the code, which necessitated rediscovering how everything works. Now, whether things belong in the issue tracker or somewhere that's more close to the code repo is probably just a cultural question, but i'd say the main thing is to have some place to store information like that.

physicles 5y ago
Staying close to the code where possible always wins, I think. One code base I worked in had a particularly complex state machine, and right above its main function was a giant ascii art diagram of said state machine. It was perfect documentation.
- KronisLV 5y ago
  Oh, definitely! I've had similarly positive experiences with temporal algebra - having some simple explanatory graphics of how two time spans would overlap is really nice!