by Simon Molloy 
As developers we have a responsibility to ensure that any code we write can be easily understood. Especially by any other developer who may come along and take on our code. Not only that, but writing code in such a way that when we ourselves come back to it, we can still recall what it does and why it does it.
This is usually where comments come into their own. Opening a class or a page, with a clear description of what it does at the top, saves a lot of time when picking up new pieces of development from another person. Descriptive lines above a method signature, listing parameters & return values etc. can also be very useful.
However there can be overkill with this approach. As documentation from Salesforce themselves shows:
Fourteen lines of code to achieve the end result. But a total of forty five lines (including spaces, granted…) in the whole class!
And as you can see, some of the method names explain perfectly what they are doing without the need for comments, as in lines 28 & 29:
// Specify the subject line for your email address
mail.setSubject(‘New Case Created : ‘ + case.Id);
In fact, the comment above is not even accurate (we’re setting the Subject on the email not the email address!).
Code over Comments
In response to this, there are some schools of thought that advocate what could be called the ‘code over comments’ approach. There are strong arguments against writing a paragraph of comments at the top of a class, and adding lines of needless comments about a method signature. Are there tools available to read and do anything with these comments? (Auto-generate technical documentation for example). Is your method signature sensibly named with a clear indication of type & name of any parameters? Will the comments always be kept up to date with every single change to the class?
I, myself, am guilty in the past of not updating that comment block. Or missing out a piece of change history. And if this happens over more than one or two iterations of a class, things become unnecessarily confusing. Particularly if the comments are seen as a crutch.
I have been working as a developer within different technologies for over twenty years. For a long time, I was a member of the ‘comment everything’ school. Particularly in my more recent years as a Salesforce developer. Working with technical architects who expected a paragraph of comments about the class, a clear change history, and comments against each and every method signature. Of course I thought this was right and proper.
Let it speak for itself
However, more recently, I have come to think that having the code speak for itself is a better approach. Of course, there are some situations where a comment could be seen as vital. Particularly explaining a strange and unexpected piece of code needed to circumvent an unusual business requirement. But these comments in your code should explain the “why”, not the “what”.
Writing clear and concise code as opposed to comments is surely a better way to go. Someone can wax lyrical in the comments of the code, explaining what the class does and why, and even explain step-by-step what the code is doing. But if the code itself is barely readable with unintuitive method & variable names and long, rambling method code that cover tens and tens of lines, then all the comments in the world will not make it a well written piece of code.
To quote Kevlin Henney;
“A common fallacy is to assume authors of incomprehensible code will somehow be able to express themselves lucidly and clearly in comments.” (from his Twitter feed).
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:
It would surely be better to break ‘myLargeMethod()’ out into smaller methods, each one taking care of each step in the code with helpful descriptive method names.
This is not to advocate the removing of all comments and never writing them again. But, perhaps it’s a better use of that valuable resource, development time, to concentrate on writing solid, clean and easily understood code that takes away the need to ‘comment everything’.
As Robert C. Martin writes in his book “Clean Code: A Handbook of Agile Software Craftsmanship” – ‘Truth can only be found in one place: the code’.
As ever, get in touch with us if you want to talk all things code.