After I stumbled upon a blog post, which headline wasExceptional Herecy, I decided to write a short blog post concerning my own heretic thoughts, which I have since abandoned. I am pretty sure that almost every programmer has heard the phrase “A good code comments itself”. However, at the time when I heard it, I could not believe it. For many years I believed that a good code contains enough comments to explain its behavior to a developer, who might have to work with it later. Since I have been developing applications with Java programming language for most of my professional career, this meant that I considered a code be good, if Javadoc markup was used to comment each method and class (except getters and setters). A few weeks ago I purchased and read a book called Clean Code, which made me realize that I have been mistaken.

I will introduce my mistakes and solutions offered by Clean Code in following:

Failure to implement methods that do only one thing. In my previous life, I used to write a methods having a name, which indicates that the method in question does only one thing. However, a more detailed inspection shows that the method has actually multiple responsibilities. Errors like this occurs when a developer does not understand the difference between a process and phases of that process. Instead of separating the phases of the process to separate private methods called from the public method, the developer writes all code to to the public method. Of course this leads in to a situation, where size of the public method is very large and code is not necessarily very easy to understand. Compare the following examples:

1public void sendRegistrationVerificationEmail(EmailDto message) {
2
3    //Construct email message by using template engine
4
5    //Send email message
6}

The comments on the previous code example simulates a code, which constructs the registration verification message by using a template engine and sends the created message. It should be clear that this method has got two responsibilities. Even though the actual source code of this method would probably not be very long, it would still do two things instead of one. The following code example illustrates, how the problem is solved:

1public void sendRegistrationVerificationEmail(EmailDto message) {
2
3    Email registrationVerificationMessage = createRegistrationVerificationMessage(message);
4
5    sendEmailMessage(registrationVerificationMessage);
6
7}

The phases of sending a registration verification email are being divided in to separate methods, which are called from the sendRegistrationVerificationEmail method. This simplifies the structure the of the source code and shortens the methods of the implementation. Thus, the result is much more understandable than the original version.

Naming variables and methods by using Stetson-Harrison method. Well, I really hope that no one will pull out the names of the variables (or methods) from a magician’s hat. For me, the greatest shock was the fact that I really did not do a very good job when selecting names for variables. The names of my methods were pretty decent, but the variables did not really describe the meaning of the variable. Instead, they described the type of the variable. This kind of approach does not really make any sense, because the type of the variable is described in the declaration of the variable. Consider following code examples:

1Email emailMessage = new Email();

This piece of code does not really reveal anything about the created variable. Following questions are left unanswered: What is the meaning of the emailMessage variable? What is kind of information does it contain? How is this variable used?

1Email registrationVerificationMessage = new Email();

The latter code example illustrates what kind of difference a good variable name can do. All questions raised by the first code example are now answered.

Using Javadocs to justify for writing bad code. Multiple problems can occur when the importance of Javadoc style comments is exaggerated. I will now describe these problems in following:

  • Javadocs are basicly a contract between an API and the user of that API. It does not actually reveal anything from the internal implementation of the API in question. Javadocs are extremely useful if you are using an API, which is not maintained by you. However, if you have to maintain the implementation of used API, you may face problems regardless of the quality of Javadoc comments. Especially, if the implementation of the API is bad code.
  • Writing Javadoc comments is not a hit and run job. The comments must be updated according to the changes made to the API. Even though this is not usually an issue, if the API in question is a public API, which is used by other developers. However, it is very easy not to update the Javadoc comments written in deep inside the application’s implementation. There are many reasons for this kind of behavior. Perhaps the developer is working in a very busy schedule and has to commit a fix for a major bug to version control system as soon as possible. After the fix has been committed, the developer simply forgots to update the Javadoc comment or decides to do it later(TM). Or maybe updating Javadoc comment is not seen as important task, because the comment lays deep in the implementation of the application, and it is unlikely that this part is never published as an public API. Never the less, this proves that Javadoc does not entirely help solving the documentation problem of source code.
  • The low quality of Javadoc comments is not helping anyone. I have myself created many low quality Javadoc comment for a method like “Sends email by using the information given as a parameter”. I regret this, but I know by experience that this is not only sin of mine, because I have seen a lot of these comments in a code written by other developers. The problem is that writing these kind of comments is the same than writing no comments at all. I am trying to say that if you decide to write a Javadoc comment, you should use all the time you need to make it as useful as possible.

After confessing my sins and writing this blog post as a sign of my remorse, I started wondering how I can ensure that I will not return back to my old habits. Clean Code talks a lot about the readability of source code. Thus, it was only natural that I decided to take this approach as a basis of my own quality control. On other words, from now on I will be aiming to create code, which can be read in a bit similar manner than a book (As long as the reader is familiar with the grammar). Also, I sincerely hope that all developers will do the same (Especially if I have to work on the same project with them).