A Few Comments on Commenting Code – When to avoid them

When writing software, the accessibility and readability of the code for other developers is important, especially when collaborating as part of a team or individuals. It helps to ensure sustainable development of a product.

However, commented code is not the same as readable code. In my experience, it is often the opposite – comments detract from the code. Sometimes they mislead another developer, other times they distract them from understanding what the code really does.

Comments are often written to compensate unclear code, so a better solution would be to write clearer code.

So when can comments be avoided?

Comments as Descriptors

When writing comments like these…

// Read in the rating for each dirty chicken shop and return the number of shops providing mega tasty chicken

String[] array = Files.readAllLines("./dcsr.txt");

int count = 0;

for(int i = 0; i < array.length; i++) {

      if (array[i].equals("5")) {

           // Tasty

           count++;

      }

}

return count;

… consider whether the code can be improved with clearly named variables, constants, methods (or different syntax altogether), instead:

String RATINGS_FILE_PATH = "./dcsr.txt";

String RATING_TASTY = "5";

private int getTastyChickenShopCount() {

      String[] ratings = Files.readAllLines(RATINGS_FILE_PATH);

      int count = 0;

      for(String rating : ratings) {

           if (rating.equals(RATING_TASTY)) {

              count++;

           }

      }

      return count;

}

Unit tests also resolve the need for some comments like these, as they describe and demonstrate how a particular function or class is used and what happens in each scenario.

Comments as Headings

Comments like these...

String RATING_TASTY = "5";

private void processRatingsFile(String inputFilePath, String outputFilePath) {

      // Read

      String[] lines = Files.readAllLines(inputFilePath);

      String[] ratings = Arrays.stream(lines)

            .map(line -> line.split(",")[2]);

      // Count

      int numberOfTastyRatings = 0;

      for(String rating : ratings) {

        if (rating.equals(RATING_TASTY)) {

          numberOfTastyRatings++;

        }

      }

      // Write

      List outputLines = Arrays.asList(

        "The total number of dirty chicken shops that have achieved the rating of \"tasty\" are:",

        numberOfTastyRatings.toString()

      );

      Path outputFile = Paths.get(outputFilePath);

      Files.write(outputFile, outputLines, Charset.forName("UTF-8");

}

… usually indicate the method/class/file is too long. It needs to be broken down and/or structured differently:

String RATING_TASTY = "5";
private void processRatingsFile(String inputFilePath, String outputFilePath) {
      String[] ratings = readRatingsFromFile(inputFilePath);
      int numberOfTastyRatings = getRatingsCountFrom(ratings, RATING_TASTY);
      writeTastyRatingsTo(outputFilePath, numberOfTastyRatings);
}
private String[] readRatingsFromFile(String filePath) {
      String[] lines = Files.readAllLines(inputFilePath);
      String[] ratings = Arrays.stream(lines)
                  .map(line -> line.split(",")[2]);
      return ratings;
}
private int getRatingsCountFrom(String[] ratings, String ratingValue) {
      int count = 0;
      for(String rating : ratings) {
         if (rating.equals(ratingValue)) {
            count++;
         }
      }
      return count;
}
private void writeTastyRatingsTo(String filePath, int count) {
      List lines = Arrays.asList(
         "The total number of dirty chicken shops that have achieved the rating of \"tasty\" are:",
         count.toString()
      );
      Path file = Paths.get(filePath);
      Files.write(file, lines, Charset.forName("UTF-8");
}

Comments as Historic Code

When a particular function or class becomes obsolete in your codebase, rather than commenting out this code, do one of the following:

  • Delete it. Rely on source control. (Personal preference - how satisfying is deleting redundant code?!).

  • Refactor it out into a distinct component, protected and documented using good unit tests that are run as part of your build pipeline.

Commented out code can go stale very quickly and adds more noise to your codebase. It can become more difficult to gauge the size and complexity of your codebase, which makes it more difficult to make informed decisions like: how easy would it be to port our codebase to another language/framework/platform?

Okay, so comments aren't always bad. Here we discuss when they can add value...

Leave a Reply

Your email address will not be published. Required fields are marked *