4 ms·
The downside of course is that comments aren't compiled/run - so they often become out of date. "Often" might actually be an understatement. I can't tell you h
by switchbak 11y ago
The downside of course is that comments aren't compiled/run - so they often become out of date. "Often" might actually be an understatement.
I can't tell you how many times I've been reading a comment that runs quite contrary to what the code really does. You then end up reading the code to reason about it anyway, paying two taxes. After too many of those experiences, you just end up going straight to the code as the source of ground-truth.
This all depends on the readability of the code / and how soon these comments get out of sync. Maybe my experience is atypical, but I doubt it.
- TheOtherHobbes 11y agoI'm sure a lot of people are hoping that one day we can generate code just by writing the comments and leaving the machine to do the rest. I certainly am.
- lmm 11y agoMore structured alternatives to comments make that kind of thing much more possible, e.g. https://hackage.haskell.org/package/djinn https://hackage.haskell.org/package/djinn
- JamesBarney 11y agoNames for classes, methods, parameters, and variables all suffer from this same problem. I think the solution to align code and comments is code reviews. Not writing comments also works but fails to solve related issues.
- u801e 11y agoWhere I work, I've always required that code that's submitted for review has a descriptive commit message. That is, the commit should explain what the problem was and how it was fixed, and why it was done that way. This way, I can run git blame (or the equivalent VCS command) on the file and get a reasonable set of comments that usually match up with the code.