3 ms·

Comments are critical to long term project quality and consistency, but they're always going to rot until tooling starts taking them seriously. For instance, i

Comments are critical to long term project quality and consistency, but they're always going to rot until tooling starts taking them seriously. For instance, it's great that code reviews have become standard practice at most organizations and for many projects, but the tooling for those reviews almost always rely on showing the few lines above and below a code diff. The reviewer has no convenient way of seeing how the changed code may conflict with any applicable comments unless the comments happen to be within those few nearby lines or the diff happens to include comment changes. Even then, the big picture is out of view and rot is still likely to seep in. It would be nice if incoming developer-support AI could start tackling this, by surfacing impacted comments and even "linting" them for applicability and accuracy.

cma 4y ago
Mayhe something like chatGPT could be fed diffs of a change and warn about comment rot and recommend fixes (once it has a much bigger context window).
alexisread 4y ago
Even better if the language supports scoping comments to particular code blocks, and comments can be made in markdown/mermaid (or equivalent) so you can diagram, link and TODO comments. Documentation tooling should be able to make a good job of constructing a class/function DAG with scoped commentary. This is kind of a reversal of Literal documentation, but I suspect it may be more maintainable by teams. Literal docs only seem to go in one direction, that is documentation->code, not the other way around. This I guess is more in-line with scientific hypotheses. Literal tests may be even more tricky as TDD doesn't gel well with Literal hypotheses. I guess a Doc-driven dev process would be a novel approach here, and probably more usable than AI-supported systems. Copilot has been quite divisive on it's effectiveness. DDD in that every eg. Class requires a comment and a test even if they are blank, to force at least a thought about them. Having a code manifest at the root of a repo can also be used to configure the envs the code runs in, and the integration tests that it needs to do both local and in-place. Lastly, as mentioned elsewhere, logs are comments as well, and again would be well to be scoped in the language.
still_grokking 4y ago
At the time we have AIs that can match up the meaning of comments and the meaning of code there won't be any need for developers any more. ;-) The other thing I wanted to mention: People don't do code review in their IDEs? Really? Modern languages with type inference are not fun to analyze without an IDE… Also you can't navigate to related code without IDE features. Just looking at a diff can be very misleading!
hesk 4y ago
So much this. I only recently started working in a big team again and when I'm doing Github code reviews I often find myself checking out the branch locally and reading the file in my IDE and then going back to the Github interface to write my review comments. Not only is this often the only way to understand the context of a change but it also makes it much easier to spot refactoring opportunities. But it's cumbersome and slow.
kmoser 4y ago
> It would be nice if incoming developer-support AI could start tackling this, by surfacing impacted comments and even "linting" them for applicability and accuracy. That only applies to comments that address what the code is doing or how it does what the comment says. It does absolutely nothing for the most critical type of comments: the ones that say why the developer decided to do it a particular way. Maybe they tried it three other ways and this was the most efficient way. Maybe they chose this way because it matches up with a business requirement that things be done in a particular order (regardless of efficiency). Maybe it must be done that way for consistency with another part of the system that is only obvious from the comment. It will be a long, long time before AI will be able to reasonably vet such comments for accuracy. Until then, comment your darn code!
baby 4y ago
I think comments getting out of date is really not that big of a deal. It’s the last of your problems most of the time.

cma 4y ago

Mayhe something like chatGPT could be fed diffs of a change and warn about comment rot and recommend fixes (once it has a much bigger context window).

alexisread 4y ago

Even better if the language supports scoping comments to particular code blocks, and comments can be made in markdown/mermaid (or equivalent) so you can diagram, link and TODO comments. Documentation tooling should be able to make a good job of constructing a class/function DAG with scoped commentary. This is kind of a reversal of Literal documentation, but I suspect it may be more maintainable by teams. Literal docs only seem to go in one direction, that is documentation->code, not the other way around. This I guess is more in-line with scientific hypotheses. Literal tests may be even more tricky as TDD doesn't gel well with Literal hypotheses. I guess a Doc-driven dev process would be a novel approach here, and probably more usable than AI-supported systems. Copilot has been quite divisive on it's effectiveness. DDD in that every eg. Class requires a comment and a test even if they are blank, to force at least a thought about them. Having a code manifest at the root of a repo can also be used to configure the envs the code runs in, and the integration tests that it needs to do both local and in-place. Lastly, as mentioned elsewhere, logs are comments as well, and again would be well to be scoped in the language.

still_grokking 4y ago

At the time we have AIs that can match up the meaning of comments and the meaning of code there won't be any need for developers any more. ;-) The other thing I wanted to mention: People don't do code review in their IDEs? Really? Modern languages with type inference are not fun to analyze without an IDE… Also you can't navigate to related code without IDE features. Just looking at a diff can be very misleading!

hesk 4y ago

So much this. I only recently started working in a big team again and when I'm doing Github code reviews I often find myself checking out the branch locally and reading the file in my IDE and then going back to the Github interface to write my review comments. Not only is this often the only way to understand the context of a change but it also makes it much easier to spot refactoring opportunities. But it's cumbersome and slow.

kmoser 4y ago

> It would be nice if incoming developer-support AI could start tackling this, by surfacing impacted comments and even "linting" them for applicability and accuracy. That only applies to comments that address what the code is doing or how it does what the comment says. It does absolutely nothing for the most critical type of comments: the ones that say why the developer decided to do it a particular way. Maybe they tried it three other ways and this was the most efficient way. Maybe they chose this way because it matches up with a business requirement that things be done in a particular order (regardless of efficiency). Maybe it must be done that way for consistency with another part of the system that is only obvious from the comment. It will be a long, long time before AI will be able to reasonably vet such comments for accuracy. Until then, comment your darn code!

baby 4y ago

I think comments getting out of date is really not that big of a deal. It’s the last of your problems most of the time.