Write code for others, not yourself

Code is complex, people are complex, code written by people is complex. When writing code it’s often thought that you write it to reach a goal. You have a feature you need to complete and you don’t stop for anything until it's done. How many times do you take a second and say to yourself “Does this make sense for people that aren’t me?” It’s hard, it's something I’ve struggled with for a very long time. Thinking about how easy to understand it is, can be very hard, it requires patience, thoughtfulness and refactoring. I can’t tell you the amount of times I’ve written some code, named a function “abcdf”, it turns out that the function now does “fdcba”. I go and change the functionality but then forget to change the name, I push my code up and everyone reading it is dumbfounded, why does his code do one thing, but it's named another?

Naming things is one of the hardest things to do in programming. It requires description, detail but not to much it's a name, you don’t want it to become to long and most of all you have to update it as you update the functionality of that function. However, it's not just the function names that can be a mess, it's the variable names too. I once worked on a project that not only had thousands of lines of commented out code in production but it had variables named “test” and “test1”. The beauty was that neither of them were being used inside of a test, they were used in production code doing god knows what. What is the point of naming these variables just about the most useless names imaginable? Laziness mostly, but also a lack of caring for the future you or most likely some poor bastard who has to workout what the fuck you just wrote. Naming things is very important.

Documentation is one of those things that some people do, others don’t, some people think it's a waste of time, others think their code is self documenting. A lot of people think documentation is a waste of time and maybe it is. You might be creating a one line function that is named “get_user” and inside the function it gets the user in one very simple line. Okay well maybe you don’t need documentation for that, but what if your calling that where there are multiple users of different kinds? Maybe it doesn’t fetch the user by “id” but by shoe size. In that case not only is your function name wrong but it's very unclear what the function does and what it needs when it's crammed in between a whole lot of other code. When it comes time to implement a big feature such as payments it really becomes vital to document your code, to plan out what your doing. Making sure everyone in the team understands what your feature is doing and how it works. When people have an easy place to go that tells them “Here’s what the feature does and he's why” it makes it really easy when someone in the future (probably you) has to debug it.

The last thing you should do before you submit your code for a pull request is to check that it actually makes sense to someone else. Have you named your functions correctly? Do they describe what the function actually does? Do your variables convey what they have captured? Does your return match what your documentation says? Does your function match what your documentation says? Does your code jump between naming conventions and/or ways of describing functionality?

I know you’ve been working on this feature for a week now, I know it’s very rapidly driving you mad, but you need to take the time to read over the code as you would an essay. Proofread it for the understanding of others, because if you don’t you will have a million questions such as “Why did you write it this way?” and “This doesn’t make any sense how are you employed here?”

At Our Very Own we have an intern program, a way to test out graduates, put them under the wing of the senior developers and see how they go. Our latest graduate blew us all away the other day. It was a relatively simple feature on the surface, but as you broke it down it became more complex than we anticipated. We broke down the feature, how it needed to work, what it needed to do, possible ways to do it and at the end we mentioned that he should plan it out, document it and then get one of us to review it before he started. Just to make sure he was on the right track, just so he properly thought out the problem. A day or two later I get an email with the Confluence page to his plan it was incredible it was detailed, easy to ready and properly thought out. He got the green light to get started. A few more days later and it was time to submit the PR, he linked the Confluence page again, only this time there was also a detailed description of how the functionality worked as it had been built. Why it had been done this way, what the tradeoffs were at a particular decision point and the benchmarks to justify it. Each function was tested, described and most importantly it was easy to read. This intern was a pro from day one. When I looked over the code sometimes I was a little confused, no matter I could go to his documentation and sure enough it was described there what was happening. This level of documentation and attention to detail doesn’t come around often but when it does it really makes it easy to understand the code. It also makes it really easy when the author of the code, comes back months or years later and doesn’t have to sit there thinking “Who wrote this? *checks git blame: O it was me…”

When you have clear, well documented code you make the lives of you and the people around you easier. Yes it takes a lot more time to document it, test it, think about naming conventions and describe your code, but the payoff is that there is a much smaller chance that the next time you look at it you will sit there in shock and awe at just how bad this code is. You can have a quick read at the function documentation or look at it from a higher level in an external tool such as Confluence. It might take you 100% more time, but it will save you 1000% more time in the future or others. As a result of spending more time planning, documenting and just generally writing code for others, you will write less error prone code and someone other than you will be able to read and maintain it.