That’s a good question, and I never through about it like that. I think that the lack of documentation isn’t that much of a problem, rather that the code stands out in the project in that it is complex to understand and requires some more though, effort and imagination to grasp, since it’s generic with lot of interfaces and polymorphism.
Now, that usually wouldn’t be much of an issue, however - the project is a game we’ve been actively working on in our spare time in a team of 2 programmers for the last 6 years, and we are all fed up with it and just want it to end. Most of the (pretty large by now) codebase is kind of simple - it’s a game code, after all, and since we started it when we were 20, there aren’t many overenginered ideas or systems, but everything is mostly written in the ugly, but simple and direct way, so if we had wanted to change something, we may have had to rewrite a part of it, but it never really needed much effort to understand what’s going on.
But now I need to change this code, which is one of the only parts that requires some kind of imagination and actually sitting down and trying to understand it, and since my motivation about the project is so low, it’s a pretty large hurdle to cross. One that is also unnecessary, since most of the generalism isn’t needed and will never be used. But since the code is written in such extensible way, it’s hard to just hack up a simple and ugly solution somewhere into it and be done with it, without really figuring out what the hell is going on.
A documentation wouldn’t help with that - it would still take the same amount of mental effort to be able to work with that code, which we generally lack in the project. I think that if I actually took the time to properly look through the code, figuring out what’s going on wouldn’t be too hard - the naming convention is pretty ok and it’s not that difficult, it just requires some mental effort.
I’m not trying to make excuses, the code very probably has problems, I’m just trying to better sort my thoughts about why I have so much problems working on it. It probably has more to do with my motivation, rather than the code in itself, and the fact that the complexity here wasn’t required, and is now a needless hurdle that actually hinders progress. Not due to it’s quality, but do to unrelated motivation issues and us having to basically force ourselves to work on and finish the damn project.
Usually it doesn’t matter what abstractions you choose when you try to factor them to support hypothetical future work, because chances are you incorrectly anticipate future needs.
In other words, generic code that only supports one use case will almost certainly have to be deconstructed to allow a good generic implementation for 2 use cases, so it is better to just write simple code and factor code out when you can see the real commonalities.
Good abstractions are important for the code to be readable. An AbstractEventHandlerManager is probably not a good abstraction.
The original commenter said that their code was “generic with lot of interfaces and polymorphism” - it sounds like they chose abstractions which hindered maintainability and readability.
In other words, you wrote nice code, but forgot to document it?
That’s a good question, and I never through about it like that. I think that the lack of documentation isn’t that much of a problem, rather that the code stands out in the project in that it is complex to understand and requires some more though, effort and imagination to grasp, since it’s generic with lot of interfaces and polymorphism.
Now, that usually wouldn’t be much of an issue, however - the project is a game we’ve been actively working on in our spare time in a team of 2 programmers for the last 6 years, and we are all fed up with it and just want it to end. Most of the (pretty large by now) codebase is kind of simple - it’s a game code, after all, and since we started it when we were 20, there aren’t many overenginered ideas or systems, but everything is mostly written in the ugly, but simple and direct way, so if we had wanted to change something, we may have had to rewrite a part of it, but it never really needed much effort to understand what’s going on.
But now I need to change this code, which is one of the only parts that requires some kind of imagination and actually sitting down and trying to understand it, and since my motivation about the project is so low, it’s a pretty large hurdle to cross. One that is also unnecessary, since most of the generalism isn’t needed and will never be used. But since the code is written in such extensible way, it’s hard to just hack up a simple and ugly solution somewhere into it and be done with it, without really figuring out what the hell is going on.
A documentation wouldn’t help with that - it would still take the same amount of mental effort to be able to work with that code, which we generally lack in the project. I think that if I actually took the time to properly look through the code, figuring out what’s going on wouldn’t be too hard - the naming convention is pretty ok and it’s not that difficult, it just requires some mental effort.
I’m not trying to make excuses, the code very probably has problems, I’m just trying to better sort my thoughts about why I have so much problems working on it. It probably has more to do with my motivation, rather than the code in itself, and the fact that the complexity here wasn’t required, and is now a needless hurdle that actually hinders progress. Not due to it’s quality, but do to unrelated motivation issues and us having to basically force ourselves to work on and finish the damn project.
Is it possible that you just chose the wrong abstractions?
Usually it doesn’t matter what abstractions you choose when you try to factor them to support hypothetical future work, because chances are you incorrectly anticipate future needs.
In other words, generic code that only supports one use case will almost certainly have to be deconstructed to allow a good generic implementation for 2 use cases, so it is better to just write simple code and factor code out when you can see the real commonalities.
In other, other words, KISS, YAGNI
Good abstractions are important for the code to be readable. An AbstractEventHandlerManager is probably not a good abstraction.
The original commenter said that their code was “generic with lot of interfaces and polymorphism” - it sounds like they chose abstractions which hindered maintainability and readability.