Recently I read and added my own comments on a LinkedIn group blog about the use of comments in code. It was interesting to see the varying ideas and how and when to use comments within code especially when talking about the Agile development model which we adhere to.
Basically the argument goes like this:
“Should developers write comments on their code to explain its purpose and what the developer is thinking about or should their code variables, functions and classes be named in such a way that anyone looking at the code would understand what was happening.”
I think in general it goes without saying that variables etc. should be named in such a way that they make sense. For example a function that is to delete should usually have the name ‘delete’ somewhere in its name but what about a more complex function that has more than one purpose. In this case it’s much harder to name it appropriately. We also need to consider that the developer is generally not the one to perform maintenance on the code throughout its lifetime. I suppose to answer the question of whether you should comment code and to what extent; you have to ask these questions.
1. How complex is the code – The complexity of the code often determines how much you need to comment. The more complex the more you need to comment. This is especially so if the developer feels they need to explain why they took a certain approach like passing variables by reference or by value to a function.
2. Who will be supporting the code after release – You have to ask yourself the question; after release what are the requirements to support the code base and who will be responsible for doing so. This is important because if the support staff didn’t write the code they will be unfamiliar with the inner workings and as such will need more time to get a thorough understanding. This of course then impacts on the time taken to fix any bugs or further develop areas, which will in turn have an effect on cost.
3. How much time have you got – With most clients you have SLA’s in place to govern how long it takes to respond to and fix issues. These timescales are not normally very long and usually mean the team doing the support has a limited time window to respond and fix the issue. At times like these the support team really needs to either have a good understanding of the code or be able to quickly understand the issue and fix the code associated.
So in summary, the question on whether code should be commented and to what level should really come down to the complexity, who will be doing the support and how much time have you got. Here at Gravity, we do advocate commenting code but only where the complexity calls for it. We believe that any code we create should be efficient, lean and understandable but we also understand the practicalities of support and want this process to be as efficient as our first-line coding.