Full Stack Web Developer
LinkedIn Mastodon GitHub Feed

Working as a Senior Fullstack Developer at Yummy Publishing (previously valantic, Sulu and MASSIVE ART),
lecturing at the Vorarlberg University of Applied Sciences,
founded and co-organizing the VlbgWebDev meetup,
used to co-organize AgentConf.

Code comments are (mostly) a violation of DRY

php, javascript, programming, documentation, dry

“Don’t repeat yourself” is such an important and widely taught concept in programming, that it has its own acronym (DRY).

Every piece of knowledge must have a single, unambiguous, authoritative representation within a system

— Wikipedia

DRY is a very powerful idea, and avoids a lot of issues, like having to fix the same bug in multiple places, because the same code has been duplicated. Many voices say that it is often overused leading to a wrong abstraction, and I tend to agree with that statement.

duplication is far cheaper than the wrong abstraction

— Sandi Metz

People often overdo the DRY principle by building abstractions the first time a problem occurs. Instead, the problem should not be abstracted before it has occurred multiple times, since it might easily lead to a wrong abstraction that might not live up to its responsibilities and ultimately causing more problems than it solves. There are already some principles like WET (Write everything twice) and AHA (Avoid hasty abstractions) that kind of contradict the DRY principle respectively limit its applicability.

While I welcome the recognition of DRY overuse in many situations, I think this principle tends to be underused when it comes to code comments, which is the topic of this blog post.

Comments often violate the DRY principle

In their fantastic book The Pragmatic Programmer David Thomas and Andrew Hunt have coined the DRY principle and they have explicitly listed that comments are a possible violation of this principle. When people are learning to code, they often get taught that good code needs lots of comments, which is absolutely not true in my opinion. Very often good code that is self-explanatory does not need any comments at all and if it does, the comment should describe why it has been implemented this way instead of just repeating what the code already says.

My favourite stack overflow question of all time deals with code comments and lists some really good examples of how not to do it (especially if you skip the funny ones, which unfortunately for this blog post are the majority).

There is one very obvious example of a bad comment:

return 1; # returns 1

This is a very obvious violation of the DRY principle, whenever the return value changes, the comment also has to be updated. But there are other not as obvious examples:

$i++; // increase by one

This is only acceptable as an explanatory comment in teaching material, but it should never make its way to a production codebase.

The fall of doc blocks

Especially in languages with weak typing documentation comments are very popular. Since these languages often don’t allow to specify types in code, people have invented ways to move that information to comments, which allows for a better understanding of the code when reading it. The alternative would be to read the code and try to find out based on how these variables are used what type needs to be passed. Popular libraries include PHPDoc and JSDoc.

/**
 * Adds two numbers
 *
 * @param int $a
 * @param int $b
 */
function add($a, $b) {
    // ...
}

Especially the @param made a lot of sense because the code itself does not expose that information in a very accessible way. But recent PHP versions improved the type system a lot and also in JavaScript technologies allowing to add type information like TypeScript get a lot more popular (compared it to Flow in another article ), which makes these doc blocks obsolete in many cases.

function add(int $a, int $b) {
    // ...
}

As a bonus, these type systems will also yell at you if the type is not correctly set, something a pure comment cannot really help with. So adding another comment just with the type annotation would duplicate that information with no real value unless the parameter is explained in more detail.

Comments tend to be ignored by developers too

The reason comments exist is to allow adding additional information to the source code in natural language. Whatever is added as a comment will be ignored by the compiler or interpreter. Developers know that, so many of them learned to ignore them to a certain degree. That’s especially true if they have ever worked with a codebase that contained outdated comments. I am always very skeptical when reading comments and double-check with the actual implementation if the statement of the comment is true because I have experienced too often that the code didn’t behave as the comment suggested.

Again, there is an answer in the already mentioned Stack Overflow question:

/**
 * Always returns true.
 */
public boolean isAvailable() {
    return false;
}

That might look like a really stupid example because it is so terribly obvious. But I totally believe that something like this can easily happen in a real codebase. Since developers tend to ignore code as well, it is not very unlikely that they don’t update the comment when changing the code for some reason.

The worst thing is that the above example is not even that bad, because after a second you’ll realize that the comment is wrong. More detailed errors in a comment are much harder to recognize because more complex code usually justifies comments, but they are only helpful if they are actually up to date. If developers don’t read comments in the first place, they are at the same time much more likely to not update them if they change something, giving them again less reason to believe in them. I would say this is a vicious circle.

Comments should add something

As already mentioned more complex code often justifies comments, at least if they describe reasons or thoughts that are not obvious from just looking at the code. But if it is considered very strict, this is already a violation of the DRY principle, because the comment needs an update too when the code changes. But it might be worth the tradeoff if the code is hard to understand.

A rule I am following is that a comment should not just repeat what the code is already saying. Another phrasing would be to say that comment must always add values, that would be missing if they weren’t there. Just recently there was a discussion in Austria about some JavaScript code for a covid-19 vaccination forecast because the code just seemed to make up some numbers. But the more interesting part of that code was the usage of comments in it:

if(now.hour() < 6) {
    estimated = ausgeliefert; // hour is before 6am
} else if(now.hour() > 17) { // hour is after 6pm
    // ...
}

The first comment basically just repeats what the line before is doing. If we need to describe what the line now.hour() < 6 is doing, then we would basically have to comment every single line in our code. The same is partially true for the next comment. It was probably written to indicate that although the code says now.hour() > 17 does not include times like 17:01. It might be a little bit better than the first comment, but I still don’t think that it is worth the tradeoff of duplicating the same information in two different places.

Another tradeoff is the doc block of the add function from above. As long as the int type hints are not part of the code itself, it makes sense to add this information, because it is much easier to find out what types have to be passed this way. If that information is not there, it might be quite hard and even need some debugging to be sure about the types that the function accepts. I guess this improvement in developer experience justifies the potential risk of the comment being outdated. But as already said above, the latest PHP versions support the type hints in code, making the comments obsolete and guaranteeing the type of the variable.

Good naming can often replace comments at all

Finally, I want to show some code, that might get rid of some comments by writing it in a self-explanatory way. This makes the code more obvious to read and since it is real code and not just comments, it is much less likely that developers won’t read it.

Let’s start with the JavaScript example from the previous section. We’ve already said that the first comment is kind of unnecessary, so we can safely omit it. The second comment kind of had a point because it was explaining in a hidden way that the hour has to be after 18:00, and even though 17:01 is after 17:00, it would not be accepted by the if statement. Another way to make this more clear is to use the >= operator instead. It removes that ambiguity and reads nicer.

if(now.hour() < 6) {
    estimated = ausgeliefert;
} else if(now.hour() >= 18) {
    // ...
}

Now the code itself is more clear and the comments could be removed, just by using a different operator.

The other two examples I am showing are real-world examples I’ve run into during my work as a software engineer. The first one is an if statement, that tries to find out if a given node represents a document that is a new one or if it has already existed before. The logic to do so was a bit cryptic, so it made sense to use a comment to explain what was happening here:

// Check if the document is a new document
if (
    !$node->hasProperty(
        $this->propertyEncoder->encode(
            'system_localized',
            StructureSubscriber::STRUCTURE_TYPE_FIELD,
            $event->getLocale()
        )
    )
) {
    // ...
}

A very easy way to avoid this comment, is to store the result of the if statement in a separate variable and give it a meaningful name:

$isNewDocument = !$node->hasProperty(
    $this->propertyEncoder->encode(
        'system_localized',
        StructureSubscriber::STRUCTURE_TYPE_FIELD,
        $event->getLocale()
    )
);

if ($isNewDocument) {
    // ...
}

This avoids the need for the above comment, and developers cannot really skip the variable name, because it needs to be referenced later. The comment would have been written in gray by the IDE, kind of telling the developer that these lines don’t really matter. By skipping reading that part of the code, it is also more likely that the comment does not get updated when the code changes.

It would be even better if this check would be part of a class so that it could be called like $document->isNew(), but that’s beyond the scope of this article.

Another example I’ve stumbled upon is the following code:

// remove the "sec:role-" prefix
$roleId = \substr($property->getName(), 9);

The above code will remove the prefix sec:role- of a string to retrieve the ID based on the name of a property. The code works, but the number 9 is a so-called magic number, so it needs some explanation, so it somehow feels natural to just add a comment afterwards. Sometimes constants are used to give such magic constants a name that better explains what it should be doing. But in this very specific example, there is also a different solution.

$roleId = \str_replace('sec:role-', '', $property->getName());

This example does not make use of code that counts the number of characters, but we are replacing the sec:role- prefix with an empty string. This way it is clear that the sec:role- prefix is removed, without the need of a comment violating the DRY principle.

I really like finding ways to write code in a way that better explains itself. Very often these changes are really subtle, but they change the way code is read fundamentally and avoiding comments altogether. I hope that these examples helped you to find some motivation to do so too!