As developers, it is our duty to ensure that the code we produce is easily comprehensible, especially by fellow developers who may inherit or collaborate on our code. Additionally, we should write code in a manner that allows us to understand it when we revisit it in the future.
This is where comments play a crucial role. Providing a clear description at the beginning of a class or page can significantly save time for developers who are picking up new development tasks. Similarly, adding descriptive lines above method signatures, outlining parameters and return values, proves to be valuable.
However, it’s important to strike a balance and avoid excessive comments. Salesforce’s own documentation highlights the potential drawbacks of an overly-commented approach.
Achieving the desired outcome takes just fourteen lines of code. However, when considering the entire class, including spaces, it spans a total of forty-five lines.
As evident, certain method names, such as those on lines 28 and 29, effectively convey their purpose without requiring additional comments:
// Specify the subject line for your email address mail.setSubject(‘New Case Created : ‘ + case.Id);
In fact, the comment above is not entirely precise, as we are setting the subject of the email rather than the email address itself.
Prioritize Code Instead of Comments
In response to this, some schools of thought advocate an approach that could be termed as ‘prioritizing code over comments.’ There are compelling arguments against the practice of including lengthy comments at the top of a class or adding unnecessary comments to method signatures. Questions arise about the utility of these comments—can tools read and utilize them, perhaps to automatically generate technical documentation? Moreover, does the method signature itself provide clear information about the type and name of parameters? And, can the comments be consistently maintained with every change to the class?
Reflecting on my own experience, I have been guilty in the past of neglecting to update comment blocks or missing out on documenting changes. Over multiple iterations of a class, this oversight can lead to unnecessary confusion, especially if comments are relied upon as a crutch.
With over two decades of experience working across various technologies, I was once a proponent of the ‘comment everything’ approach, especially during my tenure as a Salesforce developer. This was particularly influenced by working with technical architects who expected comprehensive comments about the class, a clear change history, and comments for each method signature. At the time, I deemed this practice as correct and appropriate.
Allow it to express itself on its own.
However, more recently, I’ve come to believe that letting the code speak for itself is a superior approach. While there are situations where comments may be deemed essential, such as explaining a peculiar piece of code required to address an unusual business requirement, these comments should focus on the “why” rather than the “what.”
Emphasizing clear and concise code over comments is undoubtedly a more effective strategy. Although one may provide extensive comments in the code, explaining the class’s purpose and rationale, and even breaking down the code step by step, if the code itself lacks readability due to unintuitive method and variable names or lengthy, convoluted method code spanning numerous lines, no amount of comments can transform it into well-written code.
In the words of Kevlin Henney:
“A common fallacy is to assume authors of incomprehensible code will somehow be able to express themselves lucidly and clearly in comments.
An example of excessive comments over well-written code can be seen when a developer has a very large method. To try and make the method readable, they use comments to break it down into blocks. Take this pseudo example:”
A more effective approach would be to refactor ‘myLargeMethod()’ into smaller methods, each responsible for handling a specific step in the code, with meaningful and descriptive method names.
This is not to suggest eliminating all comments and abstaining from writing them altogether. Instead, it proposes a more efficient utilization of the valuable resource of development time by focusing on crafting robust, clean, and easily understandable code, thereby reducing the reliance on the need to ‘comment everything.’
In his book “Clean Code: A Handbook of Agile Software Craftsmanship,” Robert C. Martin aptly states, ‘Truth can only be found in one place: the code.’
Feel free to reach out if you’d like to discuss anything related to code.