I want to tell you a story, that may perhaps help improve your coding in the future. Before I fully changed my music career to being a software developer, in the in between time, I was an audio engineer who did a lot of corporate A/V gigs in the washington DC area. Being the busiest markets in town, I got to work with many famous people who were for some reason supposed to be on a stage in front of the thousands of people I happened to be on the engineering crew for the show.
One of the things I never quite understood at first was why we put reflective tape on everything. Just before the show in all the corners where people were supposed to walk we put these huge pieces of tape that basically outlined a path towards the stage. Further, we made giant tape arrows and put them right in the middle of the path, along with horizontal slats of tape on all the drape leading to the stage. We also lined the edges of the stage with tape.
The reason? Although intelligent people are really intelligent at what they do, a lot of the time when they are in an unfamiliar place they still have no idea which direction to go. Why all the tape? cant they just figure it out? Isn’t all the lights on stage enough?
Well there are many obvious reasons. …but another question you must ask in this situation — is do you want to be the guy who didn’t take protective measures to keep the main guy from falling off of the stage, or tripping over the main power wires that power everything by accident? Maybe the lights were so bright he didn’t even see the tape? It’s happened. And while it looks obvious from the outside there is tape everywhere, some of these people still are so wrapped up in themselves — be it their performance, trying to remember what to say, trying to stay focused, that all the small things don’t really get thought about at all, and the end result is guys with legit 140 iq’s bumping into things they shouldn’t.
The reason we put tape there, was to show a guiding light to the incoming speaker this is the way. That way he would know which way to go. As basic as it seems. But there is also a level of psychology to this that is not immediately visible. Where the markers actually convince the person to make appropriate decisions because of the indications at a hands distance.
Another thing we did was put big fluorescent x’s where we did NOT want people to go.
This steering made for a good show, where every second is accounted for, including the time it takes for the speaker to get from the green room to the stage.
In programming, just because you know how to do something doesn’t mean it should be done that way. Like the tape, a lot of redundant code is intended to be there to ensure the person reading it that a certain path is being taken. It is a programmers propensity to refactor things to oblivion but that also makes code more obscure. The tape I described just now is like being explicit in programming. You can refactor many things to “imply” the same result with less lines of code, or technical overhead, but that doesn’t help the psychology of someone freshly walking into your codebase. Especially when what goes through the code really matters. Perceive the person on stage as content being served, Consider the coder who walks on to your codebase 6 months later when you’ve been tasked to something entirely different and cooler. You want to, with your code, steer them into making the right decisions so they can easily do the things they need to do without dropping the ball. Try to understand how your coding affects the psychology of others. Comments get ignored, and deleted, sad but true. Document your code within the code itself. Do things that are important redundantly, even twice in the same function to hammer in a point. Consider the code you write a conversation with a future person. Guide the content to the stage, embed further instructions to your descendants in the code.
In the project we are working on, I have done everything I can possibly do to guide the content out safely. Although some of the architecture seems redundant and dead simple, you have to understand there is psychology driving my decisions to code in this way. I want the content to arrive on stage safely. I want people to feel like my codebase is coherent and understandable. I want it so dumb that no one falls off of the stage.
Considering this, give another thought to two of the architecture changes you have presented:
1. make utility functions a factory.
- this takes the speaker out around the back of the ballroom through the kitchen in order to arrive to the stage. Too many files. Not easy to grasp even if it is a known pattern, it might not be one that fits or helps the content easily make it to the stage. While I dont think the architecture here is perfect, I think its easy enough for a laymen to understand what is going on.
2. refactor / unify redundant input validation
- As I mentioned earlier while things are changing rapidly I don’t think this is a good idea. Also consider someone making their own endpoint. Do they know we are doing that? Chances are they are going to avoid touching anything and make their own anyway. Psychology. Expect it.
Don’t expect to be the only one enforcing your will on the entire codebase forever more (sounds kind of boring if you ask me) Rather, expect people to contribute and guide them in by making things as dead easy as possible.
Try to take the ego out of the code. Again, just because something can be done doesn’t mean it should. I chose for loops over maps and filters for a couple reasons: Although I know how to do maps and filters I don’t because you cannot easily debug what occurs inside those functions like you can in a for loop. A for loop is like a farmers suspenders — ugly as sin but you know damn well his pants aren’t going to fall down.
