3 ms·
There’s seems to be some in-between of metadata you want to include about the code, including discussions, but is too lengthy for traditional code comments, or
by jtsiskin 6y ago
There’s seems to be some in-between of metadata you want to include about the code, including discussions, but is too lengthy for traditional code comments, or wants to reference other parts of the code, or just doesn’t mesh with traditional usages of code comments.
Often you make a decisions “I’m doing it this way because of x” that would be helpful for future maintainers to know, but would clutter the source too much.
This reminds me of this startup:
https://www.codestream.com/use-cases/code-discussion https://www.codestream.com/use-cases/code-discussion
I wish there was an totally open source, open protocol, way to do this.
- jtsiskin 6y agoAs an example, picking constants: you may have a chosen the constants based on some experimentation, but including the full details of the experiment using code comments is nonsensical. It would be great if you could still somehow have these details easily accessible from the code, but not within the source code itself. Maybe this could be done federated? ActivityPub?
- astrobe_ 6y agoCommit message bodies -> git-blame.
- AlotOfReading 6y agoI've seen many codebases outlive their version control/metadata. Source lives forever and while it may not be perfectly proper, I'd much rather have durable comments telling me how constants were derived than metadata.
- astrobe_ 6y agoHowever Git allows to salvage the history of SVN during the migration, probably because SVN was one of the most popular CVS before itself. One would expect that if something dethrones Git, it would (have to) do the same. That said, that method is not really viable if the piece of code moves too much. I would then side with the other suggestion to put that in a separate file in a doc/ sub-folder and just refer to that file in a comment. I guess that for most programming editors, "open file under cursor" is just a key combo away.
- Gibbon1 6y agoIt's the need for things like that, that makes me thing programming has outgrown raw text as a storage medium for programs. Really what you want to be able to do is link to some documentation that is a first clase part of the code base. Not some bolt on or afterthought.
- schwartzworld 6y agocomment with a reference to a different file where you explain in detail?
- cercatrova 6y agoIsn't that just documentation? You can make docs from comments so you could just put those longer comments in, even if they're long, since you're making docs out of them.