Robert C. Martin (Uncle Bob) famously wrote in Clean Code: "Every time you write a comment, you should grimace and feel the failure of your ability to express yourself in code." Clean Code It’s a harsh truth that experienced engineers eventually learn: comments lie. They don't start as lies. They start as helpful little notes. But code is a living, breathing thing. It gets refactored, debugged, and hotfixed. Often, the developer makes the code change in a hurry but forgets to update the comment sitting right above it. The moment code and comment diverge, the comment becomes a trap. A lying comment is significantly worse than no comment at all because it actively misleads the next person debugging the system. For years, the industry pushed towards "self-documenting code" - the idea that through descriptive variable names, small single-responsibility functions, and clear architecture, the code should read like prose. Then, ChatGPT arrived. The "Explain This" Trap AI has introduced a dangerous new anti-pattern into workflows. It’s incredibly tempting to take a nasty, complex, poorly named block of legacy spaghetti code, paste it into an LLM, and type: "Add comments explaining what this code does." "Add comments explaining what this code does." "Add comments explaining what this code does." The AI will happily oblige. It will parse the Abstract Syntax Tree and generate grammatically correct English sentences describing the mechanical operations of the code. You paste it back into your IDE, commit it, and feel productive. You have "documented" the legacy debt. But you haven't fixed anything. But you haven't fixed anything. You have just added noise. You have plastered wallpaper over a cracking wall. You now have messy code plus paragraphs of text that will inevitably drift out of sync with reality. plus AI, when used this way, acts as an enabler for bad habits. It reduces the friction of creating low-quality documentation. Shifting the Frame: AI as a Refactoring Architect If the goal is self-documenting code, we need to stop treating AI as a commentator and start treating it as a senior code reviewer obsessed with readability. We don't need AI to explain what the code is doing (we can read syntax). We need AI to help us structure the code so the what is obvious, leaving room for humans to document the why (the business context, the weird edge case that forced this specific implementation). what what why Here is how to change your prompting strategy to achieve clean code. 1. The "Naming Engine" Strategy Naming things is one of the two hardest problems in computer science. When you are deep in implementation details, your brain often defaults to tempVar, dataList, or processStuff(). tempVar dataList processStuff() Instead of commenting a bad name, ask AI to suggest good ones. Bad Prompt: "Add a comment explaining what the variable d holds." Bad Prompt: d Good Prompt: "I am using this variable d to store the difference in days between the transaction date and today to determine eligibility for a refund. Suggest 3 descriptive, camelCase names for this variable that would make a comment unnecessary." Good Prompt: d AI Output might be: AI Output might be: daysSinceTransaction
refundEligibilityWindow
daysElapsed daysSinceTransaction daysSinceTransaction refundEligibilityWindow refundEligibilityWindow daysElapsed daysElapsed Swapping d for daysSinceTransaction instantly removes the need for an explanatory comment. d daysSinceTransaction 2. The "Extraction Specialist" Strategy Comments are often used to delimit sections inside a massive, monolithic function. You’ll see things like // ---- VALIDATION LOGIC ---- followed by 20 lines of if statements. // ---- VALIDATION LOGIC ---- if This is a cry for help. The code is begging to be extracted into a function. Bad Prompt: "Add comments to divide this long function into logical sections." Bad Prompt: Good Prompt: "Analyze this 50-line function. It seems to be doing too many things. Identify distinct responsibilities that could be extracted into separate, private functions. Suggest names for those functions and show me the refactored main function." Good Prompt: The AI will identify that lines 10-30 are handling validation and suggest extracting them into a function named validateInputRequest(). The main function becomes cleaner, easier to read, and the comment // validation logic is replaced by an actual function call that says exactly what it does. validateInputRequest() // validation logic A Practical Example: Before and After Let's look at a typical piece of "business logic" that might exist in a codebase. The "Before" Code (Messy) // Calculates final price
function calc(i, u, t) {
  let p = i.basePrice;
  
  // check if user is premium and apply discount
  if (u.tier === 'gold' || u.tier === 'platinum') {
      // 15% off for VIPs
      p = p * 0.85;
  }
  
  // check tax exemption status based on territory code
  // some territories like 'OR' or 'DE' don't have sales tax on digital goods
  if (t !== 'OR' && t !== 'DE') {
      p = p * 1.10;
  }

  return p;
} // Calculates final price
function calc(i, u, t) {
  let p = i.basePrice;
  
  // check if user is premium and apply discount
  if (u.tier === 'gold' || u.tier === 'platinum') {
      // 15% off for VIPs
      p = p * 0.85;
  }
  
  // check tax exemption status based on territory code
  // some territories like 'OR' or 'DE' don't have sales tax on digital goods
  if (t !== 'OR' && t !== 'DE') {
      p = p * 1.10;
  }

  return p;
} This code is riddled with single-letter variables and comments explaining things that proper naming should handle. The Lazy AI Approach If you ask AI to "comment this code", you'll get noise: function calc(i, u, t) { // Function to calculate...
  let p = i.basePrice; // Initialize price to base price
  
  // If user is gold or platinum
  if (u.tier === 'gold' || u.tier === 'platinum') {
      // Multiply price by 0.85
      p = p * 0.85;
  }
  // ... etc function calc(i, u, t) { // Function to calculate...
  let p = i.basePrice; // Initialize price to base price
  
  // If user is gold or platinum
  if (u.tier === 'gold' || u.tier === 'platinum') {
      // Multiply price by 0.85
      p = p * 0.85;
  }
  // ... etc This is useless. It just repeats the code in English. The Clean Code AI Approach Let's use the prompts described above. Prompt: "Suggest better names for arguments i, u, and t in the context of a pricing function." -> item, user, territoryCode.
Prompt: "Suggest a better name for variable p." -> currentPrice.
Prompt: "Extract the logic inside the first if statement into a function that determines if a user gets a VIP discount." Prompt: "Suggest better names for arguments i, u, and t in the context of a pricing function." -> item, user, territoryCode. Prompt: "Suggest better names for arguments i, u, and t in the context of a pricing function." item user territoryCode Prompt: "Suggest a better name for variable p." -> currentPrice. Prompt: "Suggest a better name for variable p." currentPrice Prompt: "Extract the logic inside the first if statement into a function that determines if a user gets a VIP discount." Prompt: "Extract the logic inside the first if statement into a function that determines if a user gets a VIP discount." The resulting code needs zero comments to be understood. The "After" Code (Self-Documenting) function calculateFinalPrice(item, user, territoryCode) {
  let currentPrice = item.basePrice;

  if (isVipUser(user)) {
      const VIP_DISCOUNT_MULTIPLIER = 0.85;
      currentPrice *= VIP_DISCOUNT_MULTIPLIER;
  }

  if (isTaxableTerritory(territoryCode)) {
      const STANDARD_TAX_MULTIPLIER = 1.10;
      currentPrice *= STANDARD_TAX_MULTIPLIER;
  }

  return currentPrice;
}

// Helper functions (likely private)
function isVipUser(user) {
    return user.tier === 'gold' || user.tier === 'platinum';
}

function isTaxableTerritory(territoryCode) {
    const taxExemptTerritories = ['OR', 'DE'];
    return !taxExemptTerritories.includes(territoryCode);
} function calculateFinalPrice(item, user, territoryCode) {
  let currentPrice = item.basePrice;

  if (isVipUser(user)) {
      const VIP_DISCOUNT_MULTIPLIER = 0.85;
      currentPrice *= VIP_DISCOUNT_MULTIPLIER;
  }

  if (isTaxableTerritory(territoryCode)) {
      const STANDARD_TAX_MULTIPLIER = 1.10;
      currentPrice *= STANDARD_TAX_MULTIPLIER;
  }

  return currentPrice;
}

// Helper functions (likely private)
function isVipUser(user) {
    return user.tier === 'gold' || user.tier === 'platinum';
}

function isTaxableTerritory(territoryCode) {
    const taxExemptTerritories = ['OR', 'DE'];
    return !taxExemptTerritories.includes(territoryCode);
} No comments needed.The naming, structure, and extracted helpers explain everything. Conclusion The purpose of code is communication - between humans, across time. You are communicating with your future self and your teammates. While AI tools are awe-inspiring, we must be vigilant about how we use them. Using AI to generate comments on bad code is like using a high-end label maker to organize a hoard of garbage. how Don't lower the bar just because AI makes it easy to do so. Use AI to raise your standards. Demand that it helps you write code so clean that comments become unnecessary.

The "Comment" Fallacy: Why Self-Documenting Code is Still the Goal

About Author

Comments

TOPICS

THIS ARTICLE WAS FEATURED IN

Related Stories

Flip the Script: Write the Tests, Let AI Write the Implementation

The Noonification: How Often Do NFTs Pass The Howey Test? (1/13/2023)

Darwin's Hybrid Intelligence to Align AI & Human Goals for Startups & VCs

The Noonification: White Man (11/26/2022)

The Noonification: The Metaverse is a Sh*tshow (11/2/2022)

100 Days of AI Day 1: From Newsletter to Podcast, Leveraging AI for Audio Transformation

Flip the Script: Write the Tests, Let AI Write the Implementation

The Noonification: How Often Do NFTs Pass The Howey Test? (1/13/2023)

Darwin's Hybrid Intelligence to Align AI & Human Goals for Startups & VCs

The Noonification: White Man (11/26/2022)

The Noonification: The Metaverse is a Sh*tshow (11/2/2022)

100 Days of AI Day 1: From Newsletter to Podcast, Leveraging AI for Audio Transformation

Light-Mode

Classic

Newspaper

Minty

Dark-Mode

Neon Noir

Minty

HN StartUps