Where would you place the working description for a function?

Question

i like to think out a function using comments before writing it. I'd like to keep the information in the code as comments somewhere but i don't know where it should be kept. At the moment i keep it at the top of the functions code like this:

int Lattice::Width() const
{
    /*
     * Description 1
     * -------------
     * 1. Calculate the width of a lattice.
     *
     * Description 2
     * -------------
     * 1. Determine the starting point in the graph.
     * 2. Traverse in the -x direction.
     * 3. Keep count of how many traversals have been made.
     * 4. Traverse in the +x direction.
     * 5. Keep count of how many traversals have been made.
     * 6. Calculate the total number of traversals = width.
     *
     * Description 3
     * -------------
     * 1. Determine the starting point in the graph.
     * 2. Traverse in the -x direction.
     * 3. Keep count of how many traversals have been made.
     * 4. Traverse in the +x direction.
     * 5. Keep count of how many traversals have been made.
     * 6. Calculate the total number of traversals.
     * 7. The total number of nodes is the number of
     *    edges + 1 for the starting node.
     */
    
    Node* starting_node;            /* Starting point of the lattice */
    Direction* traverse_direction;  /* Direction of traversal */
    unsigned int traverse_count;    /* Number of traversals */
    unsigned int node_count;        /* Number of nodes in the width */
    
    starting_node = this->center_node;
    traverse_direction = new Left();
    traverse_count = 0;
    node_count = 0;
    
    while (starting_node != nullptr) /* Calculate number of traversals left */
    {
        traverse_count++;
        starting_node = starting_node->Traverse(traverse_direction);
    }
    
    delete traverse_direction;
    starting_node = this->center_node; /* Reset to the starting point */
    traverse_direction = new Right(); /* Change direction */
    
    while (starting_node != nullptr) /* Calculate number of traversals right. */
    {
        traverse_count++;
        starting_node = starting_node->Traverse(traverse_direction);
    }
    
    node_count++;
    
    delete traverse_direction;
    
    return 0;
}

Where should i be placing this type of documentation?

Answer 1

Documenting your process for writing the code is not necessarily helpful for later readers of the code. Some of these aspects are worth preserving, some are not. For example, having multiple versions of the description is not helpful.

However, your comments are helpful because they explain the intent of some of the code. To make those comments more useful, you could move them to the code corresponding to the step. For example, the explanation that you need to add 1 for the starting node could be added to the node_count++ statement.

The other alternative is to make the intent more apparent in the code, for example by introducing named functions for some aspects. I assume the function would be clearer if it looked like this:

static int count_traversals(Node const* node, Direction const& direction) {
    int count = 0;
    while (node) {
        count++;
        node = node->Traverse(&direction);
    }
    return count;
}

int Lattice::Width() const {
    Node* starting_node = this->center_node;
    auto left_steps = count_traversals(starting_node, Left{});
    auto right_steps = count_traversals(starting_node, Right{});
    return left_steps + right_steps + 1; // +1 for the starting node
}

Note how the name count_traversals() is self-documenting and captures your intent without requiring further comments. Keeping most of your other comments would largely repeat what is spelled out in the code, and would not add further value (in my opinion as someone who knows C++ well, other people might still appreciate more natural-language explanation).