Why ChatGPT Generated Code Documentation Isn't A Good Idea

Or at least, not yet 😁.

Some examples of ChatGPT-generated code documentation are floating around, usually as part of content promoting the awesomeness of ChatGPT. While ChatGPT is fantastic as a tool in the developer’s repository, I advise against committing ChatGPT-generated code documentation into source control until it improves.

Here’s an example of generated comments:

pub fn recalculate_victory_points(&mut self) {
    // Initialize the victory_points variable to 0
    self.victory_points = 0;
    // Iterate through the cards in the deck, adding the fixed victory points of each card to the total
    self.victory_points += self
        .deck
        .iter()
        .map(|card| card.fixed_victory_points().unwrap().unwrap())
        .sum::<i32>();
    // Iterate through the cards in the discard, adding the fixed victory points of each card to the total
    self.victory_points += self
            .discard
            .iter()
            .map(|card| card.fixed_victory_points().unwrap().unwrap())
            .sum::<i32>();
    // Iterate through the cards in the hand, adding the fixed victory points of each card to the total
    self.victory_points += self
            .hand
            .iter()
            .map(|card| card.fixed_victory_points().unwrap().unwrap())
            .sum::<i32>();
    // Iterate through the cards in play, adding the fixed victory points of each card to the total
    self.victory_points += self
            .in_play
            .iter()
            .map(|card| card.fixed_victory_points().unwrap().unwrap())
            .sum::<i32>();
}

The inline-comments are all generated by ChatGPT. The immediate pattern is that the comments focus on the “what” rather than the “why.” This makes them redundant as the code already describes the “what.”

If it still helps you read the code, it may be a signal that refactoring may help. For example, is readability better if you extract a function with a meaningful name?

Helpful Analogy #

One analogy that helps me write better documentation: Imagine a close friend who visits your home during vacations and stays for a few days. What are some things you would provide to your friend to help them be more comfortable?

1. Map of the house: Perhaps verbally, but you tell them where the bathroom, the kitchen, etc. are.
2. WiFi Access: How they can get online.
3. Quirks & Features: You have a home automation system that turns off all lights automatically at midnight.
4. Off-Limits Areas: It could be a storeroom or someone else’s room.

Good code documentation is the same for your codebase. Also, it is written since it must be conveyed so often.

Good code documentation helps colleagues to #

1. Function Independently : Figure out how to do everyday tasks on their own. Clarify abstractions with detail that matter. Explain idiomatic ways to get things done. Provide examples or test-harnesses .
2. Build a Mental Model of Codebase : Explain the functional pieces and how they work together. Provide a birds-eye view of the moving components.
3. Appreciate Why Things Are The Way They Are : Reasoning for past choices. For example, why radix sort has been chosen over quick sort (limited range of values).
4. Be Cautious : Understand the side-effects of code . For example, “break-the-glass” code that is supposed to only be used in emergencies, if you know exactly what you are doing.