George Fakidis general tech/CS/programming blog

The problem

Arguments from both sides of the debate:

No commentsComments
Code should be self-explanatory.Prose can express a wider variety of concepts.
Maintenance burdenOnboarding can be easier.
RedundancyPresent limitations can be documented.
Compiler can check codeDomain knowledge is shared.

The solution: Comments-Toolkit

Arguing about no-comments vs. comments is like arguing about tabs vs. spaces. We solved that debate with tooling years ago: we use it in editors, configure projects with it, and we barely talk about it anymore. Instead of wasting time on conventions, we relied on tooling.

Proposal: Comments-Toolkit handles comments more rigorously, in a way similar to code, with checks in:

How it works

Stamped comment example

What the checker looks for

Violations are emitted for each of those checks in the desired format (editor / GitHub pipelines). Each violation has a level: Warning, Error or Note, configurable per check with a config file.

Examples

Not updating the comment

Code

Violation

Comment that does not reference code (unstamped)

Code

Violation

Comment has a dependency

Code

Violation

Ways to use it

Design goals

Roadmap to V1

Future ideas