Share it now!

Hello, how are you?
Let’s talk about Clean Code? The first’s articles you will find here: Clean Code – Part 01, Clean Code – Part 02
I have changed the Clean Code subject order and today we will be talking about Comments:

  • Comment telling the “why” – Your comment must tell the “why” of the methods being invoked and not “how” it works. The “how” part must be clear when you read the code. When we write how the code works as comments your code will tend to have a bad design, and it will have no patterns. You might start to trust that your comment will explain how the method works instead the code itself. Remember that your code should be “self-explaining”.
    /**
     * This method publishes the documents using a proxy connection
     * to save the files in the necessary patterns
     * There is a loop (repetition) on going while the methods does not end
     * 
     */
    public void publishDocuments(){
        // some code...
    }

    The methods comment is written what it does and the way it executes the process, but this must but noticed when we read the code, not when we read the comment. If we have methods that were inside an exported package, which purpose would have to the user reading that kind of comment? The user must only know what this method does. Let’s see how a comment can be clearer:

    /**
     * Method that publishes the files, in html, which save them 
     * Applying w3c patterns.
     * 
     */
    public void publishDocuments(){
        // some code...
    }

    The comment must describe methods purpose, and the why of its existence, and do not give information about its implementation.

  • Do not abbreviate – It is not a good idea to shorten the words in the comments, shortened words make your comments difficult to read and to understand.
    //Hold ref to cli PPV
    Account account = daoFactory().getDaoAccount.getAccount();
    //Holds the reference to the clients Pay Per View
    Account account = daoFactory().getDaoAccount.getAccount();

    Writing the comment without abbreviating it you will expend just a little more time but it will make easier for anyone to read it at the first time. Recall: “You create your code so other people might read it; it defines you as a professional”.

  • Do not comment the obvious – There is some kind of codes that does not need any comment and when you do it, you decrease the quality of your code. And it’s so easy to do this…
    /**
     *Methods that calculates the bill total value
     * 
     */
    public void calculateBillTotalValue(Customer customer, Bill notPaidBill){
        // Creates the closed bill date with "today" date
        Date closedBillDate = new Date();
        
        // Sets unPaidBills to zero
        int unPaidBills = 0;
    
        // Check if the bills has the payment delayed
        if (notPaidBill.isPaymentDelayed(closedBillDate)){
            // If the payment is delayed add some interest
            notPaidBill.addInterest(closedBillDate);
        }
        
        // some code...
    }

    The code above didn’t need of that kind of comment, and the method comment just repeats the methods name. When your code is clear, you won’t need to comment every line.

    /**
     * Method that calculates the total bill value that has to be paid, add interest if needed.
     * 
     */
    public void calculateBillTotalValue(Customer customer, Bill notPaidBill){
        Date closedBillDate = new Date();
        int unPaidBills = 0;
    
        if (notPaidBill.isPaymentDelayed(closedBillDate)){
            notPaidBill.addInterest(closedBillDate);
        }
        
        // some code...
    }

    We are able to read the code above in a clear way, without needing those comments. If you have to much unnecessary comments your code gets dirty, huge, hard to read, and worst, can turn the people that read it angry.

  • /* end for */ or /* end while */ – Putting this kind of comment is useful only when you got nested repetitions(loops).
    while ( /*  while controller */){
        while ( /*  while controller */){
            while ( /*  while controller */){
                
            }/* end while */
        }/* end while */
    }/* end while */
    car.turnOffEngine();
  • This kind of comment makes the reading clearer when we got a sequence of nested repetitions (loops), but it turns harmful when we have just one repetition(loops):

    while ( /*  while controller */){
    }/* end while */
    car.turnOffEngine();

    PS.: If you have a lot of nested repetitions(loops) maybe it’s time to split them in separated methods.

  • Comments overplus [1] – When you put too many comments in your code, you get a dirt code, hard to read. The focus of someone that reads it will go to the comment instead the code, which should be the one receiving the focus. When you have a clean code there is almost no needing of putting comments, and even better, it raises tracking chances when are looking for some business bug code, because, your focus will go to the code instead of going to the comment.
  • Comments overplus [2] – If your see a lot of comments in one of your methods maybe it is time to do some refactor. Your code must always be clear, of easy understanding. Don’t use too much words to describe your methods, if you do, there is something wrong.
  • Warn about consequences – Always let the user know if your method has any consequence after been invoked. There are some methods that may affect the software behavior in an unexpected way. As sample: clear temporary files, erase database data and to start a process of remote connection that would overflow the server processing.
  • Required Comments – A clear code it’s able to eliminate most of the comments. Use comments just when it’s really needed, let your code speak for itself.

I hope this post might have aggregate some value to your knowledge. Any doubt? Just comment that I will answer.
See you soon.