A code comment is text embedded in source code that the compiler or interpreter ignores. It exists for human readers: the author, a teammate, or a future maintainer trying to understand what a program does and why. Every general-purpose language provides syntax for it, from C-style /* … */ and // to the hash mark that begins a comment in Python and shell. Because comments are stripped before the machine runs anything, they carry no behavior and impose no runtime cost; their entire value is communication.
Python’s official style guide, PEP 8, lays out the discipline that most modern style guides share. It distinguishes block comments, which apply to the code that follows and are indented to match it, from inline comments, which sit on the same line as a statement. PEP 8 advises using inline comments sparingly and warns that they are “unnecessary and in fact distracting if they state the obvious,” for example noting that a line increments a counter when the code plainly already says so.
The central rule of good commenting is to explain the why, not the what. The code itself already states what it does; a comment earns its place by capturing intent, constraints, trade-offs, or the non-obvious reason a line exists, the kind of context that cannot be read off the syntax. This is why a comment restating an expression is considered noise, while a comment explaining that a magic offset compensates for a hardware quirk is considered valuable. Comments document the gap between what the code says and what the author knew.
The recurring hazard is comment rot, also called drift: code changes but its comment does not, so the annotation slowly becomes a lie. PEP 8 states the principle bluntly, that comments that contradict the code are worse than no comments, and urges programmers to always make a priority of keeping comments up to date when the code changes. A stale comment actively misleads, because a reader trusts it over the code it describes. This fragility is the strongest argument for the self-documenting style.
Self-documenting code is the school of thought that the best comment is often no comment at all, achieved by making the code itself clear: descriptive names, small functions, and named constants instead of unexplained literals. Advocates such as the clean-code tradition argue that a clarifying name beats an explanatory comment because the name cannot drift out of sync the way prose can. The goal is not to ban comments but to reserve them for what code genuinely cannot express on its own.
In practice teams blend the two approaches. They write expressive code to minimize the need for narration, then add comments for intent, edge cases, references to specifications, and warnings. A specialized cousin, the TODO comment, marks deferred work directly in the source. Across all of these forms the discipline is the same: a comment is a promise to the next reader, and like any promise it has value only if it is kept current.