Background
Comments keep appearing that describe a change rather than the code — "now refuses", "no longer", "previously", "were already … before", "Unchanged here", "Pre-existing, but…". They read as notes to the reviewer of the commit that introduced them, which is the one audience that stops existing once it merges. They also go stale silently, because nothing contradicts a claim about the past.
Two things to do.
1. Investigate how to stop them being written
Investigate creating a skill to sweep comments on current work in a branch to remove diary style comments. Resource here shared by Stu for further reading.
2. Scan the repo for existing ones
Worth covering lib/ and test/, comments and docstrings alike.
Grep alone is not enough. The obvious phrasings are easy to find, but the same habit shows up without any keyword to catch — a docstring that explains a past fix in plain prose, or one citing a function that has since been deleted. Reading the comments a given author has added, rather than pattern-matching them, finds a different and larger set.
Categories worth looking for:
@moduledoc and @doc describing a past fix — these publish to hexdocs and IDE hover, so they are worse than an inline comment- notes addressed to the reviewer of the commit ("Pre-existing, but…", "Inherited behaviour, not a ruling")
- references to issue or PR numbers in code
- claims about intent that nobody can actually support
- references to functions or modules that no longer exist
Out of scope
The wider question of @doc/@moduledoc volume
Background
Comments keep appearing that describe a change rather than the code — "now refuses", "no longer", "previously", "were already … before", "Unchanged here", "Pre-existing, but…". They read as notes to the reviewer of the commit that introduced them, which is the one audience that stops existing once it merges. They also go stale silently, because nothing contradicts a claim about the past.
Two things to do.
1. Investigate how to stop them being written
Investigate creating a skill to sweep comments on current work in a branch to remove diary style comments. Resource here shared by Stu for further reading.
2. Scan the repo for existing ones
Worth covering
lib/andtest/, comments and docstrings alike.Grep alone is not enough. The obvious phrasings are easy to find, but the same habit shows up without any keyword to catch — a docstring that explains a past fix in plain prose, or one citing a function that has since been deleted. Reading the comments a given author has added, rather than pattern-matching them, finds a different and larger set.
Categories worth looking for:
@moduledocand@docdescribing a past fix — these publish to hexdocs and IDE hover, so they are worse than an inline commentOut of scope
The wider question of
@doc/@moduledocvolume