The Three Types of Comments
Developer Discovers Comments Have Categories; Mind Blown
Not all comments are created equal. Understanding the different purposes of comments will help you write the right kind at the right time.
1. Documentary Comments
The "passport" of your code. These comments document the file's identity, history, and purpose.
/** * File: CustomerService.cs * Author: Jane Developer * Created: 2024-01-15 * Last Modified: 2024-03-22 * * Purpose: Handles all customer-related * business logic including registration, * authentication, and profile management. * * Dependencies: Database, EmailService * * Change History: * - 2024-03-22: Added email verification * - 2024-02-10: Fixed timezone bug */
Include: Filename, author, dates, purpose, dependencies, change history
2. Functional Comments
The "to-do list" of your code. These mark work in progress, known issues, and areas needing attention.
// TODO: Implement caching for performance
// FIXME: This breaks with Unicode input
// HACK: Workaround for vendor bug #1234
// XXX: Needs security review before release
// DEBUG: Remove before production
Pro tip: Most IDEs can search for these markers. Use them consistently.
3. Explanatory Comments
The "why" of your code. These explain reasoning, business logic, and non-obvious decisions.
// We use a 30-second timeout because the
// payment gateway occasionally takes 25+
// seconds during peak hours. See incident
// report INC-2024-0142 for details.
var timeout = TimeSpan.FromSeconds(30);
// Intentionally using >= instead of > here.
// Business rule: orders of exactly $100
// qualify for free shipping (per PM decision
// in meeting 2024-02-15).
if (orderTotal >= 100) {
ApplyFreeShipping();
}Rule of thumb: If you had to think about it, write a comment.
Quick Check
You discover a bug that you can't fix right now due to time constraints. Which comment marker should you use?