Source Code Comments not in Source Code

Expert Source Code Analysis

From the dawn of computer programming, source code has been more efficiently and accurately understood if the author provides a human language description of the source code.

As such, I have sometimes been asked to provide the number and density of comments that appear in the source code as a measure of whether the produced source code is sufficient for expert analysis. Tools like Scitool’s “Understand” product and the open source “cloc” tool measure comments inside source code written in a variety of computer programming languages.

Sadly, such measurements have often shown an insufficient number or density of comments in the source code.

However, the following are other potential locations that might contain descriptions of the source code…

Internal Architecture and Design Specifications

Architecture and design specifications are the obvious first type of documents in which to look for source code descriptions, but these sometimes contain descriptions that are too high-level.

Wiki Comments

Most modern software projects maintain one or more wikis that are used by employees to collaborate on various issues. The conversation threads in these wikis can give insight into the source code and are often for:

  • Architectural and Design issues; using tools like Confluence, Trello and Notion
  • Product issues; using tools like Jira and Front

Commit Comments

All modern software projects use one or more source code version management tools (e.g., git and svn). The logged commit comments made by authors can give insight into the changes made to source code files.

Source Code Story Arc

An under-appreciated advantage of the conversation threads in wikis and logs of commit comments is they provide a story arc for the source code. 

Each single version of source code provides only a snapshot in time. Since a distinct start date and end date are often relevant to a case, only the versions of source code that were released in that date range are produced. However, the conversation threads and commit comments made before the start date and after the end data can sometimes provide insights into the produced source code.