How to make good use of comments
Tags: comments, bestpractices
Published: 2022-08-07 15:07:30

---
title: How to make good use of comments
published: true
date: 2022-08-07 07:30:28 UTC
tags: comments,bestpractices
canonical_url: https://mindsers.blog/post/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](https://mindsers.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.

```swift
/*
 * 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.

```swift
/*
 * 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.

```swift
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…).

```swift
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)
    }
}
```