DEV Community: Rodrigo 👨‍💻🤙

Comments are useful. You just need to learn when to use them

Rodrigo 👨‍💻🤙 — Tue, 28 Sep 2021 23:04:45 +0000

Perhaps you may have heard some of the following statements:

"Code needs to be self-explanatory"
"Comments are useless"
"Don't write comments in your code"
"Comments are a code-smell"
"Comments are an anti-pattern"

The thing is that writing comments aren't bad at all if you know in which cases they can help us and on which others they are a complete waste of time.

Code needs to be self-explanatory

Code should be expressive and intention-revealing. Needing comments to explain the code means the code doesn't describe itself well enough.

Our code is read far more times than is written, so we should aim to make it as easier to read as we can.

Sometimes it's clear when a comment is redundant.

// Calculate the square root of the sum of two numbers
const result = Math.sqrt(a + b);

// Timeout of 30 seconds
const timeout= 30000;

But other times, knowing if the use of comments is a good or bad idea, is confusing.

Consider the following example:

Can you know in less than ten seconds, what the code does without reading the comments?

/*
* Calculate the total amount to pay for a pizza going through each
* item in the order and obtain the cost of each ingredient of the
* price object searching by section and ingredient name to then add 
* each subtotal and return the total to pay
*
* @param {object} o: pizza order
* @param {object} p: ingredients prices
* @return {number} total: total price to pay for the order
*/
function total(o, p) {
    let total = 0;

    Object.keys(o).forEach((key) => {
        if (key !== 'ingredients') {
            total += p[key][o[key]];
        } else {
            o.ingredients.forEach((value) => {
                total += p.ingredients[value];
            });
        }
    });

    return total;
}

In the above code, we used JSDocs, which is a fancy way to create documentation automatically by reading the comments and special tags like @param or @return that specify the parameters and the value returned by each function. Although JSDocs has justified use, when used for the sole purpose of describing what the code does, it becomes useless.

We can refactor the previous example using descriptive and meaningful variable names, moving some logic to a smaller function so that its name explains what the function does. After that, we will soon realize that all such comments are unnecessary.


function calculatePriceToPay(pizzaOrder, tableOfPrices) {
    let totalPrice = 0;

    Object
        .entries(pizzaOrder)
        .forEach(([section, item]) => {
            totalPrice += getItemPrice(section, item, tableOfPrices);
     });

    return totalPrice;
}


function getItemPrice(section, item, tableOfPrices) {
    let price = 0;
    if (Array.isArray(item)) {
        price = item.reduce((accumulator, subItem) => {
             return accumulator +=  tableOfPrices[section][subItem];
        }, 0);
    } else {
        price = tableOfPrices[section][item];
    }
    return price;
}

The only reason to hesitate before removing those comments is if the JSDocs is actually been used to create documentation, if not, or if they were another type of comments we could remove them immediately.

See?. The calculatePriceToPay function is much simple to read after the refactoring even without the comments.

When we write code with intention revealing and easy to understand, every previous comment whose sole purpose was to explain the code, lose completely its value, and therefore we can remove it

Avoid using comments to explain "What"

Whenever you find comments used to explain what the code is doing I invite you to question if they are really necessary because in the majority of cases those comments aren't needed, and can be deleted.

We should understand what the code is doing after reading it line by line and not by reading a description.

Another reason is that code is alive, it changes more frequently than comments and even documentation, so it's more likely to see comments become obsolete sooner than you think.

As in everything, there are exceptions. There is one case in which we can use comments to describe the code; If we are building a really complex algorithm or performing complex operations, in non-trivial domains like statistics, physics, chemistry, healthcare. In those situations, we can give additional context and reinforce the self-described code through the use of comments.

Let's see an example:

 import math

EARTH_RADIUS_KM = 6371

def get_distance_km(src_lat, src_lng, dest_lat, dest_lng):
"""
Calculate the linear distance between two points in the earth using
the Haversine Formula

The points are GPS coordinates with a latitude and longitude 
represented as floats numbers
"""   

    DEGREES_TO_RADIANS = math.pi / 180.0

    # Convert latitude and longitude to
    # spherical coordinates in radians
    phi_src = (90.0 - src_lat) * DEGREES_TO_RADIANS
    phi_dest = (90.0 - dest_lat) * DEGREES_TO_RADIANS

    theta_src = src_lng * DEGREES_TO_RADIANS
    theta_dest = dest_lng * DEGREES_TO_RADIANS

    # Compute spherical distance from spherical coordinates.
    cos = (math.sin(phi_src) * math.sin(phi_dest) * math.cos(theta_src - theta_dest) +
           math.cos(phi_src) * math.cos(phi_dest))
    arc = math.acos(cos)


    distance_in_km = arc * EARTH_RADIUS_KM

    return distance

As you can see above, even with a clean code, it's difficult, near to impossible to understand what the code does. Why is that?, It's because it requires domain-specific knowledge. The variable names represent mathematical symbols and formulas but none of them give us context to understand what those formulas are needed, the use of comments, in this case, guides us through the steps and delivers us additional context.

With the use of those comments, we can quickly search on google for "Haversine function" and "spherical coordinates" to get the missing information.

Write comments to explain "Why"

Comments are a great tool to explain things that cannot be explained through the code.

They are good for express the reasons behind our decisions and provide additional context.

Why we write the code in this way?
Why we took that decision?
Why we are using this library?

Cases where is a good idea to use comments:

Add links to issues that are affecting our code

// Needed to handle Webpack and faux modules
// See https://github.com/fastify/fastify/issues/2356
// and https://github.com/fastify/fastify/discussions/2907.

Explain exceptions to our code style

// Typescript quirk - libraries exported with `export = ` need to be imported using `require()`.
// See: https://github.com/microsoft/TypeScript/blob/master/doc/spec.md#1135-export-assignments
import chaiShallowDeepEqual = require('chai-shallow-deep-equal');

Redirect to an external source of information

// Override timezone formatting for MSSQL
// link: https://stackoverflow.com/questions/47056395/how-to-pass-a-datetime-from-nodejs-sequelize-to-mssql

Justify our choices when writing the code

// Some errors contain not only line numbers in stack traces
// e.g. SyntaxErrors can contain snippets of code, and we don't
// want to trim those, because they may have pointers to the column/character
// which will get misaligned.
const trimPaths = (string: string) =>
  string.match(STACK_PATH_REGEXP) ? trim(string) : string;

Build automatic documentation

/**
 * Initialize a new `View` with the given `name`.
 *
 * Options:
 *
 *   - `defaultEngine` the default template engine name
 *   - `engines` template engine require() cache
 *   - `root` root path for view lookup
 *
 * @param {string} name
 * @param {object} options
 * @public
 */

Prevent unexpected errors by providing warning messages

// This file is autogenerated by build/build-validation.js, do not edit

Explain business decisions

/**
 * This module contains code that will be migrated into 
 * its own service
 * DO NOT ADD MORE CODE INTO THIS MODULE
 * see epic: https://jira.example.com/browse/PM-32145
**/

What comments should we avoid?

Comments can lie, that is a fact that can create confusion because, unlike code that keeps evolving, comments are rarely updated because it's not our priority as developers

In addition to redundant comments, we should avoid those that are implicitly or explicitly time-limited.

For example, the famous TODO or FIXME comments are used to let everyone know that there is a debt in the code that we must pay in the future, but the future could never come, and no one will review the code when the team needs to prioritize work. Instead of those comments, create a task in your task manager and label it "Technical Debt" to track how much debt the project generates and how much is paid in each iteration.

Conclusion

Comments are just another tool to solve a specific problem. The problem here is the lack of understanding after reading our code.

They aren't the bad of the movie, but they can become a waste of text so it's important to know when they are beneficial and when using them is nonsense.

As a general rule, write comments when you need to provide additional information that cannot be expressed through clean code.

If you like the article and want to support me to write more content like this, you can invite me a coffee

How we change our client’s thought that we were a slow team

Rodrigo 👨‍💻🤙 — Fri, 02 Oct 2020 13:59:49 +0000

One day, at the end of the sprint, my manager calls me. Very polite tells me that our client is upset and worried because he doubts we could deliver the product on time to the release date. We were hours before the end of the sprint, and I was busy trying to fix a problem in the checking account balance endpoint of our API. It was a complex problem that requires a lot of testing, but my manager didn’t understand why. He starts asking me some questions about our processes and methodology, trying to get to the problem’s root. He keeps asking until one of those questions triggers me.

Don’t you think that five days is too much time to finish just one endpoint?

I Immediately react, trying to justifying the time invested, perhaps so fast and in a high tone that my boss thought I was furious and tried to calm me down. He starts saying that he doesn’t enjoy making me work until late, neither in my day off (yup, I wasn’t supposed to working that day; it was an earned day off). He says that we were doing something wrong, and in the retrospective, we’ll together discover the causes with the team.

After the phone call, my impression was that he doesn’t know how difficult the problem was and all the team’s effort to recover us from a delay caused by the client’s changes at the last moment. That day the sprint review went all right, the project manager from the client side was pleased with our work, but the problem wasn’t him otherwise their boss. Until the call, we always had been thinking that we were doing right. These thoughts explain why it took the whole team and me for a surprise to know that our client wasn’t satisfied with our performance.

The day after the call with my manager, I decided to try his words, and after thinking about it, I started to believe that maybe he was right. We were doing something wrong because the time wasn’t enough to finish our work even with all the team’s extra effort.

We end it up moving the retrospective to the next day. On that morning, we receive a mail from our manager moving the meeting to another hour because he wanted to participate. When I saw the reactions of my teammates, well, there wasn’t much enthusiasm about it. So, because I was preparing myself to talk about the problem, I volunteered to lead the meeting and do the Ishikawa’s diagram to discover the causes of our client’s wrong impression of us. After a very long meeting with a lot of collaboration and constructive discussion, we came to this.

Ishikawa’s from the retrospective

It resulted in many causes that influenced our client’s perception. Some of them were poor communication, lack of information to start the sprint, changes introduced after planning, lack of crucial processes, and external factors not considered when planning. We recognize that all these problems came from a bad implementation of Scrum. It was the first time we used this framework. Without proper training, it would likely look like a Zombie Scrum implementation with many anti-patterns.

As a team, we resolve to implement two solutions: one in the short term and the other in the long way. In a short time, we made an extraordinary deploy to production to accomplish the client release date. After that, we set some actions to correct the remaining problems in the next few sprints.

Here are the actions that we implement and the learnings that we gain.

Know what they want and let them know what you need

In the scrum framework, this is called the definition of ready. It means that the requirements to develop a user story should be identified and completed before starting to work on it. For example, we can’t start working on an endpoint that should use the client’s database model -given by them- without knowing the details of the model, the business meaning of the tables and columns, ordering, possible filters, and so on.

When you have identified these requirements, ask for them, be clear and set a deadline to the client, explaining that if they don’t meet the deadline, the user story will be re-prioritized and excluded from the following sprint. All this was made at the refinement meeting when we revisit some stories to polish their definitions and identify dependencies between them whenever possible. Also, discovering the development tasks needed to accomplished the story.

Anticipate to changes, communicate at a fast speed when things happened

Sometimes the client isn’t clear about what user stories prioritize to develop them on the next sprint and change his mind barely hours before the start. One strategy to prevent this is to have the backlog updated and estimated with user stories to add and swap from the suggested sprint. That way, we can give the client the flexibility he needs to prioritizes according to the results and past events. There were other cases when the stories that were planned suffer changes in their definition or something unexpected occur that requires immediate attention and we need to include it in the sprint. Thus, it’s crucial to inform the team when these cases arise and update stories and acceptance criteria to reorganize the active sprint.

Have the backlog updated and estimated with user stories to add and trade from the suggested sprint. That way, you can give the client the flexibility he needs to prioritizes according to the results and past events.

It’s essential to back up every change and agreement made with the client. Do this via email and copy it to every stakeholder for transparency, indicating the changes’ impact and how the development team will act according to these changes. Explain to the customer when a delay may happen because of the changes and advise him when to stop adding, updating, or removing stories. Additionally, it’s crucial to explain what they can exchange from the current sprint to include new stories; ideally, it should always be work equivalent in effort.

There is always space for improvement: Optimize your development cycle

When your clients think that your team is slow, it’s related to three main problems:

Bad communication
Unoptimized workflow
Unattainable commitments

They don’t understand what you are doing or how you do it, so you have a communication problem. Also, maybe you aren’t satisfying the client expectations about what should be delivered and when; this could be caused by an unoptimized workflow or setting higher expectations that you cannot accomplish (unattainable commitments problems).
Having and unoptimized development workflow is a tough one because even by resolving it, you can’t be sure that your client will change their mind if you keep setting unattainable commitments.

Optimize your development cycle and search for dead spaces in the sprint. Understand why team members are waiting until someone finishes a story needed to start working on their own stories.

Invest time on:

Implementing CI/CD
Test automatization
Refine stories until you have almost only independent and small stories.
Increase the coverage, boost the confidence to refactor the code
Refactor what you can to allow easy extendability and maintainability.
Reduce loss time, use contracts, and API specs to split the development so that nobody has to wait until others finish their work. (try swagger virtualization). Keep an eye on the number of dependant stories in the sprint. It could mean that the team is planning badly.
Revisit your git workflow and implementation. Maybe it isn’t the most suitable for this project.
Search for tools to increase the team’s productivity: code generators, CLI, libraries, packages, frameworks.
Begin to measure; the time to finish stories, how many times a story is blocked, occurs unexpected events that affect development?. Then set actions together on every retrospective to eliminate the bad behavior and maintain good practices.
Reduce the batch size of the sprint. That way, you reserve free space for unplanned work.

The primary purpose is to gain more time through automation and use that time on any unplanned work during the sprint. Also, keep watching any constraints to avoid possible bottlenecks on the sprint.

There is always room for improvement, so you must increase team efficiency to be effective. After eliminating one of the reasons why the team is considered slow, you’ll see a boost in productivity but beware of unattainable compromises. Measure the velocity and capacity of the team, explain it clearly to the client before building the next sprint, and remember never to plan above the maximum capacity of the team, or you’ll continue losing the client’s faith for not meeting your commitments.

Be the technology expert: Explain your development workflow to the client

Even these days are companies that don’t know how software is made, perhaps because they don’t need to know to use it. But, it’s valuable for the team that your client knows this type of information. It can help to understand why you make some decisions or why it’s too challenging to build something in a short period.

As a software engineer — or any equivalent role — It’s expected that you identify obstacles and risks to develop an application or system. You and your team are the technology experts, so behave like that and express your thoughts, emphasize what is essential and crucial to do for the project’s sake from a technological perspective. Also, inform the consequences of sacrifice quality against velocity. Even if you don’t work for an external client you are the technology consultant for the company that hires you.

Some clients have an IT area and maybe they do things faster than your team. But that doesn’t mean they do it right, this way of thinking can be easily changed when you explain why there is a development process with defined stages and what does every step in the process. Why you expend time writing tests or why sometimes is necessarily doing a refactor before adding new functionality.

The trick is explaining to your customer that they are paying for a product that is expected to be durable, that should fulfill a necessity, and to do so you need to focus not only on building new features fasts but also on doing it right. It should be a concern no only to make the software but also to prepare it to be easy to maintain, that way, it remains valuable for a long time and at a low cost.

Build a trustworthy relationship by improving the communication

One of the main things that helped us to change our client’s perception was to improve communication. We increase the dialog through phone calls and emails and always show them respect and a complete compromise to do our best for their product. But, there is a difference between making our best effort and do everything right. Sometimes you can commit errors and accidentally delete the client’s data or take down a reviewed service during a meeting. These things can happen all the time, and rather than trying to hide our blame someone else, it has more value to be transparent and honest.

There are plenty of companies and professionals capable of doing the work that your client needs, so always focus on building a trustworthy relationship; this adds value on top of high-quality products and is an advantage over your competition.

Mistakes are hidden opportunities to win the confidence of your client, all depends on how you approach them.

If you commit a mistake, don’t worry. Tell your client the situation and explain the options to solve the problem, also design ways to ensure that it will not happen again. The same approach can be applied when there are delays in the planning, raise your hand early to reveal what happened, and what should be the actions to prevent these delays.

Now, continuing with the story

In the next sprints, we apply and keep track of all the actions described above. We deliver more without sacrificing the quality by organizing the stories better and improving the timing between requesting the required information to start working on a story and added into a sprint. Also, we increase the messages in the communication channels and transparent any problem or external events that could affect the planned work.

We change our mindset from following the client’s indications without arguing to proposing better approaches and solutions to their product.

We notice changes in the attitude during the sprint reviews. The product manager and the manager itself -from the client-side- start to give us compliments about our work. They were genuinely impressed with the quality and the compromise of the team. They tell our manager that they were astonished about the team performance and velocity; they appreciate the effort and are glad for the results.

The changes that we implement helped us to make an impact on our relationship with the client. Now they understand and also believe in our way of work, all because of the outstanding results. In the final weeks of the project, they only call our boss to compliment and coordinate new opportunities for working together.

With all the team’s compromise to implement the actions described in this article, we manage to deliver a high-quality product that satisfies our client’s needs and changes their opinion about us.

The process described here is summarized in the diagram. It’s an iterative process in which we first use a neutral approach taking all the complaints to analyze them and discover insights that tell us what we are doing wrong. Then we set actions to correct bad behavior and improve the good ones. The most significant change introduced was to invest time teaching and educating our clients to know how we work and the benefits of our methodology. To keep the whole process sharp, we keep track of every experiment and action defined through metrics. That way, we know what is working and what should be corrected or discarded.

Perhaps the process described here is not suitable for your problems, and even if it does it, you may not have the same results with your clients.

Remember that every client is a different world, and for some of them, it is more important to meet a deadline rather than have a fully tested, robust, and reliable system.

You should invest time talking with your clients to know what their worries are. Usually, a product owner knows these things but is vital to transmitting to every team member to be aligned and on the same page.

We went through everything due to Scrum’s poor implementation and not having the proper knowledge, neither a coach nor a scrum master. Getting out of that situation was very difficult, so I suggest starting well and hiring an agile coach or an experienced scrum master to teach the principles and values to all those involved in developing the product, but most importantly to the non-developers. Your team will save a lot of headaches if you can count on that support.