Inaccurate Comments

Incomplete Base

Structure: Simple

Description

This weakness occurs when code comments do not correctly describe or explain the actual behavior of the associated code. Misleading comments create a disconnect between what the documentation says and what the program actually does.

Extended Description

Inaccurate comments introduce confusion and inefficiency during code reviews and security audits. Reviewers must spend extra time verifying actual behavior against stated intent, slowing down the validation process and increasing the risk that subtle logic errors or security flaws will be overlooked. Over time, this inconsistency makes code maintenance significantly harder, indirectly harming security. It becomes more difficult to identify root causes of bugs or vulnerabilities, and developers are more likely to introduce new defects when modifying code they do not fully understand due to misleading documentation.

Common Consequences 1

Scope: Other

Impact: Reduce Maintainability

Potential Mitigations 1

Phase: Implementation

Verify that each comment accurately reflects what is intended to happen during execution of the code.

Demonstrative Examples 1

In the following Java example the code performs a calculation to determine how much medicine to administer. A comment is provided to give insight into what the calculation shoud be doing. Unfortunately the comment does not match the actual code and thus leaves the reader to wonder which is correct.

Code Example:

Bad

Java

public class Main {

java

In the correction below, the code functionality has been verified, and the comment has been corrected to reflect the proper calculation.

Code Example:

Good

Java

public class Main {

java

Note that in real-world code, these values should be validated to disallow negative numbers, prevent integer overflow, etc.

References 1

Providing a Framework for Effective Software Quality Assessment

Robert A. Martin and Lawrence H. Shafer

07-1996

https://www.researchgate.net/publication/285403022_PROVIDING_A_FRAMEWORK_FOR_EFFECTIVE_SOFTWARE_QUALITY_MEASUREMENT_MAKING_A_SCIENCE_OF_RISK_ASSESSMENT(2023-04-07)

ID: REF-963

Applicable Platforms

Languages:

Not Language-Specific : Undetermined

Related Weaknesses

ChildOf:

Inappropriate Source Code Style or Formatting (CWE-1078)