The latest articles on DEV Community by Tanya Kamenskih (@tanya_kamenskih_fae915d43). https://dev.to/tanya_kamenskih_fae915d43 https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F4062538%2F404a3cfa-f85f-44a2-8a5c-db5a2cea7798.png https://dev.to/tanya_kamenskih_fae915d43 en Tanya Kamenskih Wed, 12 Aug 2026 11:32:45 +0000 https://dev.to/tanya_kamenskih_fae915d43/why-comments-should-explain-the-reason-not-repeat-the-decision-32hg https://dev.to/tanya_kamenskih_fae915d43/why-comments-should-explain-the-reason-not-repeat-the-decision-32hg <p>A code comment is useful when it adds context that cannot be understood from the code alone. Simply repeating what the code does creates noise without helping the next person make a change safely. The most valuable comments explain why a particular decision was made.</p> <h2> The Code Already Shows What Happens </h2> <p>A comment such as <code>// retry the request three times</code> adds little value when the code clearly contains a loop with three attempts. It duplicates information that can become outdated if the implementation changes.</p> <p>Instead, a useful comment might explain that the limit exists because the remote system temporarily rejects repeated requests. This context is not obvious from the loop itself and helps future engineers understand which parts are safe to modify.</p> <h2> Reasons Preserve Important Context </h2> <p>Technical decisions are often shaped by constraints that are no longer visible in the code: compatibility requirements, performance limits, ordering guarantees, or behavior of an external system. Without that context, a later change may look like a harmless cleanup but reintroduce an old problem.</p> <p>A comment should therefore answer questions such as:</p> <ul> <li>Why is this approach used?</li> <li>Why is this value unusual?</li> <li>What constraint prevents a simpler solution?</li> <li>What behavior must not be changed?</li> </ul> <p>The explanation should be concise and focused on the decision’s rationale, not on the entire history of the discussion.</p> <h2> Keep Comments Accurate and Specific </h2> <p>A reason-based comment is helpful only while it remains true. Avoid vague phrases such as “important” or “temporary fix” without explaining the relevant constraint. If the constraint changes, update or remove the comment together with the code.</p> <p>It fills the gap between implementation and intent, making future changes easier to evaluate.</p> <p>When writing a comment, describe the problem the code is solving rather than narrating the code line by line. The implementation may change, but the reason behind the decision often remains the most useful part for the next engineer.</p> coding programming softwareengineering