Back to course

Writing the Code Story: Effective Comments and Documentation

The Art of Vibe Coding: Aesthetics, Elegance, and Emotional Intelligence in Software Development

Lesson 5: Writing the Code Story: Effective Comments and Documentation

Comments are not a substitute for clear code, but they are essential for clarifying complex intent, architectural decisions, and handling edge cases.

The Comment Vibe Paradox

If your code requires comments to explain what it does, the code itself lacks clarity (Bad Vibe). Comments should explain why the code is written the way it is (Good Vibe).

When to Comment (Good Vibe)

  1. Clarifying Intent (The Why): Explaining a non-obvious design choice, especially performance optimizations or workarounds for external libraries/bugs.
  2. High-Level Summaries: Providing a Docstring/Javadoc at the beginning of a complex function or module to outline its purpose, inputs, outputs, and side effects.
  3. Warnings and TODOs: Marking areas that need future attention (TODO: Refactor this into a dedicated service later.).

python

Good Vibe Comment: Explaining the architectural 'why'

WARNING: This hack is necessary because the legacy API (V1) returns time

in local timezone, violating standard UTC practice. Must remove when V2 is live.

timestamp = adjust_for_legacy_tz(response['time'])

When NOT to Comment (Bad Vibe)

Avoid commenting on the obvious. These comments clutter the code and add noise.

javascript // Bad Vibe: Obvious commentary // Loop through the list of users for (let i = 0; i < users.length; i++) { // Increment the counter by 1 count++; }

Documentation Vibe (External)

Good Vibe Coding extends beyond the file. Ensure your module-level documentation (Readmes, API docs) are easy to find and use. A developer should be able to clone your repo and get started without reading your mind.