Why documentation is more important than code

Taking a break from the machine learning heavy posts, I would like to talk about something slightly different but very important: documentation. Which is more important: code or documentation? If asked, most developers would say that code is more important than documentation. As a developer, you are given some business requirements and are asked to deliver a solution. That solution is your code. It works and solves the problem. Done!

There is nothing wrong with this argument. At the end of the day, code gets the job done. And if you’re on a tight schedule such as trying to fix a production issue then yes, your code is way more important. But that’s not the scenario I am talking about. I am talking about most of the development that gets done where developers are given sufficient amount of time. That’s when you must document your code. Whether that be through comments or separately on a wiki page, it is your responsibility as a developer to add that additional information for your team.


Developers should be practical, not perfectionists

There is barely any time when I can say I learnt a particular skill in college which I use in my daily professional life. Being able to build circuits? Nope. Triple integration? Nope. Calculating poles and zeros of a transfer equation to be able to optimize your circuit? Nope. However, one skill I do use is being practical. As an (electrical) engineer, I learnt to build stuff good enough to function. I learnt to focus more on practical aspect of things rather than purely theoretical. This concept was reinforced when I started my first job as a programmer. It was more important to have a functional code that could be delivered on time than to have the perfect code that took months, if not years, to write. My clients cared about results and budget. This is not to say they didn’t care about quality but they cared about it only to the extent that was necessary. But how do you know what level of quality is good enough?

As a programmer, many times, you will have to decide whether to make your code ‘better’ (and sophisticated) or to leave it in its current functional state. You wrote the code that meets your client’s requirements and everyone’s happy. Do you go the extra mile and make sure all the boundary cases are accounted for? Even the ones that you think have fewer chances of occurring than you winning a million dollar lottery tomorrow? It’s because of such scenarios that I am able to proudly say I am not a perfectionist. I am a practical guy who assesses each situation and determines what level of quality is required. I do not write code that will last for two decades because I know that due to the dynamic nature of the industry I work in, no code will survive that long. Why bother wasting my team and my company’s resources for something that will never be utilized?


When it comes to estimating effort, be pessimistic

This is the first post in the WorkTip series that I am starting on Enlist q. I have been working full-time as a developer for about 4 years now and have learnt so much that can only be learnt through experience. I have been lucky enough to be surrounded by some great minds and mentors who have not only taught me how to code but also how to adapt to the business environment. I realize that not everyone is as fortunate and that’s precisely why I would like to share what I have learnt with you! Stay tuned!

For several months after I started work, I was shielded from clients. My manager prioritized the work and assigned it to me. I would then attempt to finish the task and fail (this is when I was still learning q, kdb, linux…pretty much everything). My manager would help me out and with his assistance, I will finish the task and pass it back to him. Done. It was a simple process.