Confessions of a Code Quality Heretic

After I stumbled upon a blog post, which headline was Exceptional 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:

public void sendRegistrationVerificationEmail(EmailDto message) {

    //Construct email message by using template engine
 
    //Send email message
}

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:

public void sendRegistrationVerificationEmail(EmailDto message) {

    Email registrationVerificationMessage = createRegistrationVerificationMessage(message);

    sendEmailMessage(registrationVerificationMessage);

}

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:

Email 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?

Email 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).

10 comments… add one
  • Foo Apr 16, 2010 @ 15:31

    Good stuff

  • Attethoto Aug 20, 2010 @ 16:16

    i'm new... expectancy to brief nearly more often!

  • Arttu Aug 28, 2010 @ 16:39

    I wish they would teach this stuff at least at the university level. Clean Code was an eye-opener for me too. Kind of stupid that they are concentrating on making students write a lot of documentation to explain their code when the time should be used to clean the code so it doesn't need documentation.

    I still write way too long methods and often break, for example, the single responsibility principle, but thanks to this kinds of books, I am going to right direction.

    This is one part I am disappointed to university level education since they only concentrate on higher level things and consider coding as a trivial implementation. I don't know if there is any "school" at all that would also handle this part of the software development, but there should be. Of course the best coders, the ones that really care, will make effort to become better, but don't know if it's the best way.

  • Petri Aug 30, 2010 @ 14:15

    Arttu,

    I totally agree with you. I am not sure what is the current content of programming courses, but when I was taking them, code quality was not really addressed at all. The lecturer made some comments about commenting the source code and selecting the names for variables and methods. That was basicly it.

    I sincerely hope that things like refactoring and unit testing are explained and expected from students. Of course it would be best, if it would be obligatory for software engineering students to take a course concentrating solely on quality of source code. Naturally, Clean Code should be used as a study material for that course.

  • Arttu Aug 30, 2010 @ 23:09

    I can speak only based on my experiences from the University of Eastern Finland (Joensuu campus), and I think your situation sounds very familiar. Our courses covered only the very basics. Code quality was not really addressed at all, and we didn't really have too many purely programming courses. I really hope that things are better in other places.

    I have played with the idea of "programming school", where students would only... code, working in teams, trying out different things like TDD, pair programming etc. with the help of skilled teachers. I don't know if any of these exists, but there should be. (Some game programming schools seems to be working a bit like this.)

  • Petri Aug 31, 2010 @ 8:49

    I studied in the Tampere University of Technology, but I have heard similar stories from my friends studying across Finland. In theory, the problem might be the goals of university education, which tries to teach people about theory and the "advanced" stuff. The problem is that in Finland most of the people graduating from universities (at least in the IT industry) usually ends up doing software development (programming, writing specifications and so on). These tasks require a more pragmatic approach, and it might very well be so that some skills learned at the university are not useful in real life.

    In theory, universities of applied science should be teachning programming to their students. The problem is that quality of education given in this institutes is varying. I know places, which are great, but sadly I have heard stories of not so great places as well. Since I have not myself studied in this level, I find bit hard to make a sound comment about the given education, but I feel that teaching many different programming languages is common practice. I believe that the goal should be to concentrate on one aspect of software development and train people to be professionals in that area (Mobile development, Desktop, Web and so on). Perhaps this would also help the students to get that first job from an IT company.

  • Jose Sep 3, 2015 @ 11:26

    Right on!There is no excuse westaohver for not commenting code, it is just pure laziness and/or sloppiness.Some people have told me it takes too much time - this is also pure nonsense.I can, however, understand people if they don't care about the code they write and admit it.

    • Petri Sep 4, 2015 @ 22:16

      Actually, nowadays I try to write as few comments as possible. I write Javadocs for classes, interfaces, enums, and all public methods that aren't simple getters or setters.

      Other than that, I concentrate on making my code so clean that it doesn't need comments. Of course, if I cannot do that for some reason, I add a comment that describes how the code works and why it works that way. Also, since we review each commit before it ends up to the master branch, other developers can ask me to clarify something if they want to.

      This practice has served us well, but who knows what we will do in the future.

  • Juha Mar 9, 2016 @ 16:28

    I just loathe abundant verbosity when using variable names. I love my code beautiful and pleasing to the eye. When you're trying to make your code self-commenting you make it darn ugly, less readable and pain in the ass when trying to modify it. You'll get typos, you'll forget what the heck was the variable name again, you'll run out of decent row length when editing or viewing the code. And did I already mention it's ugly as hell? Instead of desperately avoiding the comments:

    Email registrationVerificationMessage;

    try:
    // E-mail message to verify registration
    Email verification;

    • Petri Mar 12, 2016 @ 18:31

      Thank you for your passionate comment. I wrote this blog post almost six years ago, and I have to admit that I have changed my mind. I still want to write self-documenting code, but I have realized that long variable names might not necessarily help me to achieve that goal. Nowadays I tend to think more about the context and the "surroundings" of the object in question.

      For example, if I am writing a registration method that is supposed to send a user account verification email, I don't want to repeat that information in the variable name because the name of class (Email) and the context (registration) leads into the conclusion that the constructed Email object must be the user account verification email.

      Thus, like you suggested, the string: 'verification' is a perfect name for this variable.

Leave a Reply