{"post":{"slug":"how-to-comment-your-code-2026","title":"How to Comment Your Code in 2026: Write Comments That Help","excerpt":"Good comments explain why, not what. Here is how to write comments that age well, when to skip them, and the habits that keep code readable for years.","category":"code","date":"June 14, 2026","author":"ByteLedger Team","content":"<span class=\"dropcap\">G</span>ood code comments explain why, not what. The code itself already shows what it does, so a comment earns its place by capturing intent, reasoning, or context that the code cannot express, like why you chose an unusual approach or what edge case forced a workaround. The best habit is to write clear code that needs few comments, then add notes only where the why is not obvious. In 2026, with AI tools generating and reading code constantly, comments that record human intent matter more than ever.\n\n## Why comments exist at all\n\nCode tells the machine what to do. Comments tell the next human, often your future self, why it does it that way. A line that looks strange might be a deliberate fix for a tricky bug, and without a note explaining that, someone will eventually \"clean it up\" and reintroduce the problem.\n\nThat is the core principle: comments should add information the code cannot convey on its own. If a comment merely repeats what the code already says, it is noise that will rot the moment the code changes.\n\n```python\n-- Weak comment: just repeats the code\ntotal = total + 1  -- add one to total\n\n-- Useful comment: explains the why\ntotal = total + 1  -- retries are counted separately per the API rate-limit rules\n```\n\n## Good comments versus bad comments\n\n| Comment type | Example purpose | Keep it? |\n|---|---|---|\n| Why a decision was made | Explaining an unusual approach | Yes |\n| Edge cases and workarounds | Noting a fix for a known bug | Yes |\n| Public function documentation | Describing inputs and outputs | Yes |\n| Restating obvious code | Narrating a simple loop | No |\n| Outdated notes | Describing removed behavior | Delete |\n| Commented-out code | Old code left behind | Delete, use version control |\n\nWhen in doubt, ask whether a reader who knows the language would learn something from the comment. If not, it probably should not exist.\n\n## How to comment well\n\n1. **Write the code clearly first.** Good names and small functions remove the need for most comments before you write any.\n2. **Comment the why.** Capture intent, trade-offs, and the reasons behind non-obvious choices.\n3. **Flag the surprising parts.** Workarounds, edge cases, and anything that would make a reader pause deserve a note.\n4. **Document public interfaces.** Functions others call benefit from a short description of what they do and expect.\n5. **Update comments with the code.** Treat a stale comment as a bug, because a wrong comment is worse than none.\n6. **Delete dead notes and code.** Version control remembers old code, so do not leave it commented out.\n\nCleaner code naturally needs fewer comments, so reinforce this with [how to write better code](/blog/how-to-write-better-code-2026), and pair it with [how to name variables](/blog/how-to-name-variables-2026) to reduce the need for explanation in the first place.\n\n## Common mistakes\n\n- **Narrating obvious lines.** Comments that restate simple code add clutter and hide the comments that matter.\n- **Letting comments go stale.** Code changes but the comment does not, and now it actively misleads readers.\n- **Leaving commented-out code.** It confuses readers and your version control already keeps the history safely.\n- **Over-commenting to look thorough.** Volume is not value; a few precise notes beat a wall of narration.\n\n## What to skip\n\n- **Skip commenting self-explanatory code.** If a clear name already says it, a comment just repeats and ages poorly.\n- **Skip apologizing in comments.** Notes like rough or fix later without context help no one; either fix it or explain the plan.\n\n## FAQ\n\n**Should I comment every function?**\nNo. Document public functions others rely on, but private helpers with clear names often need no comment at all.\n\n**Is it bad to have too many comments?**\nIt can be. Excessive comments hide the important ones and tend to go stale. Aim for clear code with a few meaningful notes.\n\n**What is the difference between why and what comments?**\nA what comment restates the code and adds little. A why comment explains intent or reasoning the code cannot show, which is what makes it valuable.\n\n**Do AI coding tools change how I comment?**\nThey raise the value of intent. AI can read code, but comments that record why a human made a decision still guide both people and tools.\n\n## Where to go next\n\n[How to write better code in 2026](/blog/how-to-write-better-code-2026), [How to name variables in 2026](/blog/how-to-name-variables-2026), and [How to write a function in 2026](/blog/how-to-write-a-function-2026).","hue":195,"metaTitle":"How to Comment Your Code in 2026","metaDescription":"Learn how to comment your code in 2026: explain why not what, avoid stale and obvious comments, and write notes that keep your code readable for years.","keywords":["how to comment your code 2026","code commenting best practices","how to write good comments","when to comment code","code documentation tips","clean code comments","why vs what comments","commenting code for beginners","readable code 2026","good code comments examples"],"tldr":["**Explain why, not what** — the code already shows what it does; comments earn their place by capturing intent and reasoning.","**Clear code needs fewer comments** — good names and small functions remove the need for many comments entirely.","**Stale comments are worse than none** — a comment that no longer matches the code actively misleads readers.","**Document the surprising parts** — workarounds, edge cases, and non-obvious decisions are where comments pay off most.","**Skip:** narrating obvious lines like incrementing a counter; that is noise, not help."],"readTime":"3 min read","wordCount":760},"related":[{"slug":"how-to-write-better-code-2026","title":"How to Write Better Code in 2026: habits that last","excerpt":"Better code is readable, simple, and tested, not clever. Here are the habits that improve your code in 2026, from naming to small functions to honest tests.","category":"code","date":"June 22, 2026","author":"ByteLedger Team","readTime":"3 min read","hue":222},{"slug":"how-to-write-clean-code-2026","title":"How to write clean code in 2026: principles that actually matter","excerpt":"Clean code is not about style guides or linters — it is about writing code that your future self and teammates can understand and change safely.","category":"code","date":"April 6, 2026","author":"ByteLedger Team","readTime":"5 min read","hue":316},{"slug":"how-to-write-a-function-2026","title":"How to Write a Function in 2026: a beginner guide","excerpt":"Functions are the building blocks of every program. Learn how to write one in 2026: parameters, return values, and the habits that keep functions easy to use.","category":"code","date":"May 12, 2026","author":"ByteLedger Team","readTime":"3 min read","hue":212}],"sameCategory":[{"slug":"bazel-build-explained-2026","title":"Bazel Explained: What Hermetic Builds Actually Cost","excerpt":"Bazel delivers reproducible, precisely cached builds and demands that you describe everything. Here is what you get, what it costs, and who should say no.","category":"code","date":"August 19, 2026","author":"ByteLedger Team","readTime":"3 min read","hue":145},{"slug":"graphql-federation-2026","title":"GraphQL Federation: One Graph, Many Teams","excerpt":"Federation composes independently-owned subgraphs into a single API. Here is what it solves, the operational cost it adds, and when a simpler gateway is enough.","category":"code","date":"August 19, 2026","author":"ByteLedger Team","readTime":"3 min read","hue":300},{"slug":"hermetic-builds-explained-2026","title":"Hermetic Builds Explained: Same Inputs, Same Output","excerpt":"A hermetic build depends only on declared inputs. Here is what that property gives you, the common leaks that break it, and how to move toward it incrementally.","category":"code","date":"August 19, 2026","author":"ByteLedger Team","readTime":"3 min read","hue":130},{"slug":"monorepo-tooling-compared-2026","title":"Monorepo Tooling Compared: What You Actually Need","excerpt":"Monorepo tools solve task orchestration and caching, not repository layout. Here is what each tier provides and how to tell when you have outgrown the simple option.","category":"code","date":"August 19, 2026","author":"ByteLedger Team","readTime":"3 min read","hue":150}],"newer":{"slug":"how-to-clean-your-laptop-2026","title":"How to clean your laptop in 2026: screen, keyboard, and vents","excerpt":"Cleaning a laptop safely takes the right cloth, a little alcohol, and care near vents. Here is a step-by-step routine for the screen, keyboard, and ports.","category":"tech","date":"June 14, 2026","author":"ByteLedger Team","readTime":"4 min read","hue":320},"older":{"slug":"how-to-control-your-emotions-2026","title":"How to control your emotions in 2026: regulate, do not suppress","excerpt":"You cannot stop emotions from arriving, but you can change how you respond to them. Here is a practical 2026 guide to emotional regulation that does not rely on white-knuckling.","category":"guides","date":"June 14, 2026","author":"ByteLedger Team","readTime":"3 min read","hue":200}}