Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Info
iconfalse
titleTable of Contents

Table of Contents

Overview

A readable and understandable source code should be a balance between:

  • Documented complex or not straightforward pieces of code
  • Readable unit tests scenarios that will help the developers understand the code
  • Documented API that will help external developers understand how to use those API
  • Respect of coding standard such as naming conventions

With too many comments, you may face the following issues:

  • Time consuming maintenance that may lead to comments that are no longer up to date. Then comments go against their primary goal: they mislead the developer who will spend more time understanding the source code.
  • If the source code needs too many comments, it either means that it does not respect coding standards (naming conventions, design, etc.) or it is too complex.

Monitoring Comments

Widget

Add the Documentation & Comments widget (was Comments & Duplications widget prior to version 3.7) to your dashboard:

Coding Rule: Commented-out Code

For many languages, a coding rule is available to detect pieces of code that are commented-out.