Comment guidance - avoid cross-reference requirements, keeping things short

[slowdini]

Useful guidance to add somewhere in writing-technical-docs, claude in particular struggles to avoid writing verbose, hard-to-follow comments, due to their length and lack of encapsulation.

I think the most straightforward rules are these:

• Code comments that aren't function/doc-block comments (i.e., annotating a line, loop, etc.), should almost almost be 1-2 lines. Longer comments should be reserved exclusively for truly complicated or unclear cases, where a full read of the surrounding code can't explain the line well enough.
• 5-7 lines should be more than enough for any comment - only comments that also function as documentation in some other way should break this rule. For instance, comments that are part of CLI help docs, ones that are used to generate online docs, or other cases where a comment in the code is the reference doc for some part of the software.
• Comments should never contain cross-references, either to other comments, or sources outside of the codebase (like issues, Slack threads, etc.) - this makes comments hard to follow, and breaks good encapsulation, which should apply to code comments too. A comment is about the line, function, or other section of code that it's lexically near - reading the code itself is how someone gets a full explanation of how it works.

The line count instructions lead to a bit of an oddity where comment line length affects the application of the rule, but I think this is fine. Most programming languages have some kind of standard recommended line length for source code.