Which code is more readable?
implementation
uses
// Delphi units
SysUtils, Windows, Classes,
// Libraries
Lib.Utils, Lib.Settings, Lib.JSON,
MainFormU, // Main form unit
Settings; // Settings unit
procedure TForm.OnButton1Click( ASender: TObject );
var
Humpty: THumptyDumpty;
begin
// Set up a humpty dumpty class and execute it, passing it the personal id, name and what looking glass
// someone is passing thru
Humpty := TUmptyDumpty.Create( PersonalIdEdit.Text, NameEdit.Text, LookingGlassEdit.Text );
try
// Run the class
Humpty.Run;
// if SomethingIsTrue then
// Humpty.ExecuteAndStore('c:\tmp\falafel.txt'); // - Remove this when Im done - Ric
finally
// Make sure Humpty is always freed and nilled.
FreeAndNil( Humpty );
end;
end;
end.
Or this one…
implementation
uses
SysUtils, Windows, Classes,
Lib.Utils, Lib.Settings, Lib.JSON,
MainFormU,
Settings;
procedure TForm.OnButton1Click( ASender: TObject );
var
Humpty: THumptyDumpty;
begin
Humpty := TUmptyDumpty.Create( PersonalIdEdit.Text, NameEdit.Text, LookingGlassEdit.Text );
try
Humpty.Run;
finally
FreeAndNil( Humpty );
end;
end;
end.
All I did was remove the comments in the second example, and the code is much more readable.
In most code syntaxes, much of the code flow is implied. In Delphi, for instance, it is implied that you have an implementation section that might be followed by a uses clause. A bunch of standard units (SysUtils, Windows etc) are almost always included. This is implied, so you don’t have to comment that you include Delphi standard units.
Moreover, clarification that library units are included and what the form units do is also unnecessary as the names of the units clearly indicate that the units are libraries or hold certain forms.
The THumptyDumpty class is (presumably) clearly and descriptively named in the context of the application, the form components are explicitly named after their purpose and the THumptyDumpty class itself appears to have well named methods. Further clarification through comments are not necessary; it is easier to understand what this code does without all the cluttering comments.
Now, is all comments bad? Of course not, comments can and should be used where clarification is needed. Maybe you have a complicated algorithm that’s difficult to write descriptively in code, or a process that spans several sections of code or have a long lifetime. There are many reasons to add comments to your code, but clarifying code that is already clear and readable is not one of them.
What is the problem with unnecessary comments? Well, there’re many reasons, but the most important ones in my opinion are
- Comments clutter code
- Comments mould
- Comments steal focus from both the author and the reader
Comments clutter
If it’s not worth saying, you shouldn’t say it. If you say it anyway, it clutters. It doesn’t add to the overall understanding of what you’re trying to say in the first place. The extra words just steal focus from what argument you’re trying to make in the first place.
It’s similar when writing code. Write your code to be self-explanatory to as high a degree as you can. There’re lots of tips on how you can do this in the literature on the clean code topic, for instance breaking up your code in smaller specialized functions and procedures, naming methods and variables after what they do and hold or breaking up logic in several steps.
Comments mould
It’s inescapable that comments mould. Over the years, chances are a lot of programmers will have changed your code. In just a few weeks after the code is finished, you yourself will have lost track of what it does. Some would argue that comments will help you and other programmers to understand the code faster, and they might be right. But most often, they’re not.
If you’re absolutely honest, are you a hundred percent thorough updating comments when you edit some code? Do you always go through all the comments in the neighbourhood, changing them, deleting them? Will you always delete old commented out code snippets someone left in the code years ago?
No, I thought not. Comments mould. Code does too, but comments mould faster. And anyway, the code needs to be there, the comments do not.
Comments steal focus from both the author and the reader
Some programmers set their IDEs to express comments in bold, screaming colours or excruciating warning background colours arguing that comments are the most important thing of the code.
I do the opposite, thinking the code is the most important thing of the code. Many programmers refuse to restrict their commenting, so in any old programmes you look through, you will find old code commented out, irrelevant or unnecessary clarifications etc. I usually set the syntax highlighting of comments to a discrete grey, so I will be able to read the comments if I need to, but disregard them if I don’t.
So why do so many programmers overly comment their code? Well, there can be many reasons, but I think one reason is that they haven’t really thought about how they write their code through. Most experienced programmers have evolved their coding practices over their careers and years, but perhaps they haven’t sat down and thought their practices through? How should methods and variables be named? How can I break this long method up to do only one thing, pushing other responsibilities out to other methods?
Naming methods and breaking them up into smaller pieces is, I think, the most import thing for readability. Naming a method well often requires you to break it up. A name shouldn’t be DoThisAndThenDoThatFollowedByTheThirdThing. such a name implies that the method does to many things.
That method should be broken up into maybe four methods, one possibly public that calls the other three (ThenDo, FollowedBy and ThirdThing) private methods that actually do something.
procedure TClass.DoTheThings; begin DoThingOne; DoThingTwo; DoThingThree; end;
Another reason may be insecurity at the workplace or in your team. Perhaps directions for how you should write your code isn’t clearly laid out by your CTO or by the team. Guidelines for clean coding in the team might be missing or wanting.
At the same time, you want to make a good impression, making a good job and deliver a well documented, well-formed piece of code. So you take extra time and effort explaining in comments exactly what your code do.
Instead, you should
- Ask the team for any guidelines that pertain to how the code should be formed. What patterns should you use? How should you structure the code you write? Are there naming guidelines?
- Write readable clean code. Comment only if there are complex flows or logic that really needs to be explained.
- If you’re uncertain about clean coding techniques, pick up any book on the subject, read it and use its recommendations. There are many good books available, and clean code is frequently discussed on online forums all over the internet.
It’s a team effort
Am I always right? Should the tips and tricks from clean coder extremists always be followed? Of course not, they are recommendations. Strong ones, yes, but still recommendations. Use them and adapt them to your own needs, or rather the needs of the team.
If you’re working alone, think of your future team. Chances are, even if you’re doing all the work yourself, someone else will need to change your code in the future. Possibly when your app’s become very successful, and you need to tweak it to make you another million dollars. It would be a sad thing to miss that million dollar opportunity just because you didn’t think your code through in the first place.
Take your ponderings and questions to the team. If the team doesn’t have coding guidelines, put the idea to set guidelines up to the team. Make an effort to get the team working towards the same goals in the same fashion. The success of the product is often of survival importance to the team. If the product fails, the team will fail.
