How to Actually Comment Code Without Wasting Everyone’s Time

Development & Code
, , , ,
1

:brain: Commenting That Doesn’t Suck

How to Actually Comment Code Without Wasting Everyone’s Time
commenting, development, best-practices, code-quality, documentation

:pushpin: Introduction

Writing code isn’t enough — someone (possibly you) will have to read, debug, or improve it later. And if your comments are vague, missing, or useless, that person’s going to hate you.

Let’s fix that.

:brain: Philosophy

“Comment to clarify why, not just what.”

Comments should clarify intent, not restate the obvious. Good comments help others (and future you) understand decisions, edge cases, and non-obvious logic.

:magnifying_glass_tilted_left: Purpose of Comments

:white_check_mark: Explain why something is done
:white_check_mark: Clarify non-obvious logic
:white_check_mark: Point to docs, decisions, or assumptions
:white_check_mark: Mark future work with TODO, FIXME, or HACK

:cross_mark: Don’t comment the obvious (i++ // increment i)
:cross_mark: Don’t write a novel inline
:cross_mark: Don’t leave outdated comments lying around

:brick: Comment Types

1. :white_square_button: Block Comments

Use these at the top of files or major sections to explain what the code is for.

# setup.sh
# Initializes FathomOS environment.
# Must be run inside a clean chroot or container.

2. :small_blue_diamond: Inline Comments

Use short inline notes to explain edge cases or weird behavior.

if user_id not in cache:
    # Avoid stale user data on cold boot
    fetch_user_profile(user_id)

3. :construction: TODO / FIXME / HACK Tags

These flag work to be done, problems to fix, or hacks to revisit.

# TODO: Refactor to systemd-native start/stop
# FIXME: Breaks if /etc/resolv.conf is missing
# HACK: Hardcoded delay — remove after upstream fix

:hammer_and_wrench: Best Practices

  • Use consistent style: # for shell/python, // or /* */ for C/Java
  • Keep it brief and on-point
  • If it’s more than 3 lines, link to a doc
  • Clean up old TODOs and remove lies
  • Make your code readable enough to need fewer comments

:card_index_dividers: File Headers for Scripts

When creating standalone scripts — like Bash, Python, or JavaScript files — it’s important to include a header comment at the top of each file. This isn’t just for professionalism — it helps future maintainers (or your future self) quickly understand what the file does, who wrote it, and when it was last modified.

Use the appropriate comment syntax for the language you’re writing in.

:wrench: Example for JavaScript

Similar header blocks should be used in Bash, Python, or whatever language you’re writing in — just change the comment style to match.

/**
 * Example Project - Main JavaScript
 * ===================================================
 * A secure, privacy-focused password generator
 * 
 * Author: Captain Dumbass
 * Version: 1.0.0
 * Last updated: 2025-06-13
 */

:white_check_mark: Summary

Good comments:

  • Are brief, relevant, and accurate
  • Help others make safe, informed changes
  • Make you look like someone who knows what they’re doing

:speech_balloon: Final Thoughts

Comment like someone else will read your code. Because they will.

Want more developer sanity guides like this one? Check out the rest of the Development & Code section or request a topic.