4 ms·
Or they will simply change or modify the code and leave the comment? Now the comment doesn't help, it's actually detrimental.
by lawn 13y ago
Or they will simply change or modify the code and leave the comment? Now the comment doesn't help, it's actually detrimental.
- dllthomas 13y agoPerhaps testable comments?
- jdbernard 13y agoWhy should we keep adding more complexity overhead to our languages and toolkits instead of finding people we can trust to do the job right?
- dllthomas 13y agoBecause there is no one we can trust to always do the job right, and so a large code base will accumulate cruft over time. Just how carefully do you search out any possible comment referencing code you change? It's not always going to be adjacent.
- jdbernard 13y agoThat's true, but at some point you cannot automate quality craftsmanship. Making comments part of the automated compile/test process in my opinion crosses the line and would be more detrimental than helpful. In this specific case I would prefer to add code review and emphasize practices like adjacency of comments to code. Code should be reviewed on a regular basis as well. We all make mistakes, but I think a habit of putting at least two eyes on it and of coming back periodically to review past work is better.
- dllthomas 13y agoI don't pretend to know it's a good idea, and there's undoubtedly poor ways to implement it, but I think it's worth exploring. Adjacency of comments to code helps, but not everything can be adjacent to everything else, and when necessarily disparate code necessarily interacts it merits a comment that cannot be local to both. Putting multiple eyes on the code is great, but 1) isn't prevented by what I propose, 2) isn't going to be perfect (and can perhaps be done more effectively with fewer things to have to check), and 3) sometimes isn't possible (if someone is working alone, for instance). As John Carmack recently put it, on a large project "[e]verything that is syntactically legal that the compiler will accept will eventually wind up in your codebase."
- jdbernard 13y agoI guess my hesitation is that I think it would probably be implemented poorly and then be forced on me by a PHB. You are right in the points you make and if it could be done so that it did not add lots of mental overhead or required boilerplate it could be a useful tool. Worth exploring, but I'll let you do the exploring. :)
- lmm 13y agoTestable documentation - or, as it's more commonly known, unit testing - is of course a very good idea, and a better replacement for comments.
- dllthomas 13y agoRelated, for sure. I think for it to be considered testable comments it would have to 1) be inline, 2) be brief enough to be easily readable in the context of a comment, and 3) be aimed at documenting the kinds of things good comments are aimed at documenting. All of these are occasionally aspects of unit tests, but there are plenty of things that are unit tests and are probably a good idea that are not all three of these.
- talmand 13y agoThat's not an indicator of comments being the problem, that's an indicator of someone that can't be bothered to update documentation.
- lmm 13y agoFeel free to believe that comments are a good idea in some mythical perfect world of perfect programmers. They're still frequently worse than useless in the real world.
- talmand 13y agoFeel free to believe that no comments at all are a good idea in some mythical perfect world of perfect programmers. Their absence is still frequently worse than useless in the real world. I suppose in the end it's just a matter of opinion, isn't it?
- ErrantX 13y agoThat's a process/standards issue, not a problem with comments! If a team is so poor that they don't properly document what they do I suspect that the comments is the last thing to worry about :)
- masklinn 13y ago> That's a process/standards issue Same with shit code and non-self-documenting code no?