How to make good use of comments

This is often what is criticized for beginners but everyone knows it, beginner or not, many developers do not comment otherwise badly on their codes.

⚠️ Read more of my blog posts about tech and business on my personal blog! ⚠️

Assuming you're here to change and start commenting your code. How to write quality comments?

DRY for comments

Writing comments is already not super fun, so avoid writing too much or writing the same information in several places.

Tell yourself that overly commented code (especially if you repeat yourself in your comments) is as bad as uncommented code. Indeed, it will quickly become off-putting and no one will read your comments, which makes them completely useless.

A technique to not repeat yourself in your comments and to make them more efficient is to reserve certain information for certain comments according to their positions in the code.

4 positions = 4 types of comments

File comments

This comment is useful for indicating the age of the file, its creator, and any other necessary file-level information.

/*
 * Converter.swift
 * EuroConverter
 *
 * Created by Nathanaël Cherrier on 19/06/2016.
 * Copyright © 2016 Nathanaël Cherrier. All rights reserved.
 */

class Converter: NSObject {
    private var _base: String!

    init(base: String = "EUR") throws {
        super.init()

        try validateCurrency(base)
        _base = base

        getExchangeRatesFor(base)
    }
}

Some IDEs automate the creation and modification of these file comments. In this case, dates, contributor names and file names will be changed when necessary.

Class comments

The class comment will gather information about the class: what it is for, its version, its compatibility, etc.

/*
 * Allows you to convert currencies
 * 
 * @class Converter
 * @since 3.1
 */
class Converter: NSObject {
    private var _base: String!

    init(base: String = "EUR") throws {
        super.init()

        try validateCurrency(base)
        _base = base

        getExchangeRatesFor(base)
    }
}

Method & function comments

These are surely the comments where you will have the most things to write. They will allow any developer using your classes to understand how to use them without even looking at the code of their methods.

If the method comments are well written, then your colleagues will thank you for saving them valuable time.

class Converter: NSObject {
    private var _base: String!

    /*
     * Initializes the class with a primary currency
     * @param base {String} Currency used as the basis for the rates 
     * (pairs base/USD, base/EUR, etc.) 
     *
     * @throws {ValidationError} Error if wrong currency 
     * is given in parameters.
     * @return {void}
     */
    init(base: String = "EUR") throws {
        super.init()

        try validateCurrency(base)
        _base = base

        getExchangeRatesFor(base)
    }
}

Precision comments

These comments are last level. They are written in the middle of the code to explain a block of complex code or certain choices (methodology, design…).

class Converter: NSObject {
    private var _base: String!

    init(base: String = "EUR") throws {
        super.init()

        // We don't catch the error here 
        // We leave the management to the user of the class
        try validateCurrency(base) 
        _base = base

        getExchangeRatesFor(base)
    }
}