There’s a piece of code in our hobby game project that I’ve written after attending classes in college about how to write clean and SOLID code. It’s the most overengineered piece of shit I’ve ever written. I’m not saying it’s the fault of the lectures, of course it’s on me being a little bit over zealous, but it does check all the boxes - It’s a simple “show selectable list of stuff”, follows MVC, it’s extensible without rewriting to adittional data-types and formats, extensible view that can show any part of data you need, generic, and in general it could be used anywhere we need, for any kind of data.
There’s only one place where we need and use such list in our game.
I needed to rewrite a part of it, since the UI changed drastically, to not need this kind of list, while also adding events into the process. I haven’t seen the code for almost 4 years, and it’s attrocious. Super hard to understand what’s going on, since it’s too generic, interfaces and classes all over the place, and while it probably would be possible to rewrite the views for the new features we need, it’s just so complex that I don’t have the mental capacity to again figure out how it was supposed to work and properly wire it up again.
I’m not saying it’s fault of the classes, or SOLID. It’s entirely my fault, because the classes inspired and hyped me with ideas about what a clean code should look like, that I didn’t stop and think whether it’s really needed here, and went over-the-top and overengineered the solution. That’s what I’d say is the danger of such Clean Code books and classes - it’s easy to feel clever for making something that passes SOLID to the letter, but extensibility usually comes at a complexity, and it’s super important to stop and think - do I really need it?
Academia has a disconnect with the industry when it comes to coding practices. Most teachers haven’t much industry experience. They don’t know how it is to maintain a 10 year old project using SOLID and clean code principles.
They just teach whatever has already been in the curriculum for decades. They don’t know that whatever they’re teaching is actually harmful in the industry.
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.
There’s a piece of code in our hobby game project that I’ve written after attending classes in college about how to write clean and SOLID code. It’s the most overengineered piece of shit I’ve ever written. I’m not saying it’s the fault of the lectures, of course it’s on me being a little bit over zealous, but it does check all the boxes - It’s a simple “show selectable list of stuff”, follows MVC, it’s extensible without rewriting to adittional data-types and formats, extensible view that can show any part of data you need, generic, and in general it could be used anywhere we need, for any kind of data.
There’s only one place where we need and use such list in our game.
I needed to rewrite a part of it, since the UI changed drastically, to not need this kind of list, while also adding events into the process. I haven’t seen the code for almost 4 years, and it’s attrocious. Super hard to understand what’s going on, since it’s too generic, interfaces and classes all over the place, and while it probably would be possible to rewrite the views for the new features we need, it’s just so complex that I don’t have the mental capacity to again figure out how it was supposed to work and properly wire it up again.
I’m not saying it’s fault of the classes, or SOLID. It’s entirely my fault, because the classes inspired and hyped me with ideas about what a clean code should look like, that I didn’t stop and think whether it’s really needed here, and went over-the-top and overengineered the solution. That’s what I’d say is the danger of such Clean Code books and classes - it’s easy to feel clever for making something that passes SOLID to the letter, but extensibility usually comes at a complexity, and it’s super important to stop and think - do I really need it?
Academia has a disconnect with the industry when it comes to coding practices. Most teachers haven’t much industry experience. They don’t know how it is to maintain a 10 year old project using SOLID and clean code principles.
They just teach whatever has already been in the curriculum for decades. They don’t know that whatever they’re teaching is actually harmful in the industry.
Oh man, taking the reference code for an academic white paper and trying to add something to it is a trip.
Almost never any thought beyond proving the point of the paper.
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.