When a use case has several moving parts, I sketch the steps as comments before I write real code. This is for the inside of a feature, not system design. Architecture needs more than a comment block.

A friend watched me do it and said people call it comment driven development. You think through the task, write the stages as comments, then translate those lines into code once the sequence makes sense. You might already do a version of this without a name for it.

Disclaimer: this is a teaching sketch. Ignore OOP purity for a minute. Ignore SOLID. Let the architect brain sit down. The example is only here to show the comment habit.

// Purchase a book

// Check book availability
// Check user balance
// Deduct user balance
// Add payment information
// Add book to library
// Generate email body
// Send purchase confirmation to email

Once the steps are on the screen, converting them is mechanical:

// Purchase a book
public async Task PurchaseBook(Book book)
{
    // Check book availability
    var isAvailable = _bookService.IsAvailable(book);
    if (!isAvailable)
    {
        throw new Exception($"{book.Title} is currently unavailable");
    }

    // Check user balance
    var isBalanceAvailable = _userService.HasEnoughBalanceToPurchase(book.Price);
    if (!isBalanceAvailable)
    {
        throw new Exception("You don't have enough balance");
    }

    // Deduct user balance
    _userService.ReduceBalance(book.Price);

    // Add payment information
    var payment = _paymentService.AddHistory(new Payment {
        Status = PaymentStatus.Paid,
        Amount = book.Price
    });

    // Add book to library
    _libraryService.Add(new Library {
        Book = book,
        Payment = payment
    });

    // Generate email body
    var emailBody = _emailRenderService.Render(EmailTemplate.PurchaseConfirmation, payment);

    // Send purchase confirmation to email
    _emailQueueService.Add(new EmailQueue {
        Recipient = _userService.GetEmail(),
        Subject = "Thank you for your purchase",
        Body = emailBody,
    });

    await _dbContext.SaveChanges();
}

When the code is in place and I trust the shape, I delete comments that no longer help.

I put the whole flow in one method here on purpose so the habit is easy to see. I am not selling procedural god methods, and I am not asking anyone to skip design. CDD helps me on concrete inner use cases with sub-steps, like PurchaseBook, where I want the sequence fixed before I start typing implementations.

For me the aim is simple: list the steps, build the feature, drop leftover comments once the code and the surrounding structure feel solid.

Why I keep doing it:

  • I catch missing steps before I bury myself in half-written code
  • I can hand the comment list to someone else as a short brief
  • The comments double as a light trail while the feature is still forming

I later wrote a follow-up about sketching failure modes the same way: Failure-mode driven development.