Pichpich (पिच पिच) is a tool to help keep different comments in sync across different parts of code and config files. Often, code and config files have complex dependency relationships like:
- When X is updated, Y needs to be updated too.
- X contains a long-form explanation for why Y is the way it is, e.g. as in GHC notes
- X and Y need to be kept in sync both ways.
and so on. Sometimes, it is possible to factor out things in a way that these are enforced by a compiler or a linter, and breaking a violation would be flagged in some way.
However, relying on a compiler doesn't always work. Some examples:
- When multiple languages are involved, keeping things in sync via code generation may in some cases be too heavy-weight, cumbersome, or just infeasible.
- When keeping docs in sync with code, writing one-off tooling can be tedious.
- Factoring things out creates undesirable build dependencies (or even cycles).
In such a situation, most people seem to gravitate to thinking that "well, it is hard to keep docs/comments in sync, that's how it has to be". That's incorrect. Specifically, it is possible to have a simple linking tool that basically does cross-reference checks across plain text files. All that is needed on top is (1) nice error messages (2) the tool should run reasonably quickly and (3) the tool should easily integrate with code review tooling/CI.
Pichpich is a WIP CLI tool which aims to address this problem.