I think “use comments for why” is a fairly popular position, so because I like being annoying I’m going to argue that it’s also a good idea to use comments for what.
First of all, why do we use comments to explain why? Why not commits? You say “you can’t expect people to look at commits”, which is a good argument, but that misses something important: using commits for why is just like using comments for what! To take your comment example, imagine you saw
# context, outlet, times, time per step, state, data
def pattern(c, o, t, l, s, d)
# ...
end
Why should I use better variable names? I’ve already left a comment saying “c is the context”, so why should I repeat redundant information? If you want to know what c is, just read the comment!
Of course that’s silly. c may be documented, but it makes understanding the function harder. We recognize that the cost of looking up what something means is a context switch that breaks flow and slows you down. It’s really inconvenient, which leads to problems. Better to replace c with context everywhere so you don’t need to look it up in the first place. Same is with why comments vs commits: it’s significantly more effort to delve through commits, even clear ones, than read a comment right there.
So what does this have to do with what comments? Let’s take a popular refactoring example: Extract till you Drop. The replace method takes a few bits of time to understand and would definitely be helped with a couple of what comments. But what if, instead of comments, you refactor it to be “self-documenting” code? The author does that, creating six more methods in the process. It’s definitely easier to read each individual method than it was before.
But if I’m not trying to understand the methods. I’m trying to understand the class. Now I have to jump all around SymbolRefactor to understand it end-to-end. In fact, while doing that, I spent way too long looking for GetSymbol before I realized it was an external call. When I went back to the original class, that fact was instantly obvious. If I was doing a code review and was sanity checking the algorithm, I’d definitely prefer the first version + what comments than the last version.
First of all, why do we use comments to explain why? Why not commits?
Why not both? My rule of thumb is to explain the why in the commits. Only if something seems counter-intuitive I’d add it as a comment. (So mostly no comments).
However I get the impressions most devs don’t have an easy way to traverse the history from the comfort of their editor. I can’t imagine living w/o Emacs’ vc-annotate
One important difference between commit messages and comments is that commit messages have a chronological context. We can talk about the previous solution in a commit message, e.g.
Don’t foo during the bar, since they can deadlock; do it during the baz instead, since we’ve definitely finished barring by that point. In particular, this will stop quux messages coming from the server, since it was running out of foobar.
In contrast, comments need to make sense to future readers who may not know or care about the way things used to work. In this case we might have a comment like:
# Foo and bar can deadlock if run together, so we only start fooing now that bar's finished
But if I’m not trying to understand the methods. I’m trying to understand the class. Now I have to jump all around SymbolRefactor to understand it end-to-end.
I agree; more concretely, a few of those extraction steps (e.g. nextSymbol) break encapsulation, introduce sequential coupling and break thread-safety. Those problems aren’t specific to this code though, they apply to all “iterators” (which I think of as the “I want to use Java’s non-OO for/in statements, and I’m willing to tear apart the remaining OO aspects of my codebase to do so” anti-pattern).
Yes, the methods are private to the class; but classes aren’t the only unit of encapsulation/modularity/information-hiding.
I think “use comments for why” is a fairly popular position, so because I like being annoying I’m going to argue that it’s also a good idea to use comments for what.
First of all, why do we use comments to explain why? Why not commits? You say “you can’t expect people to look at commits”, which is a good argument, but that misses something important: using commits for why is just like using comments for what! To take your comment example, imagine you saw
Why should I use better variable names? I’ve already left a comment saying “c is the context”, so why should I repeat redundant information? If you want to know what c is, just read the comment!
Of course that’s silly. c may be documented, but it makes understanding the function harder. We recognize that the cost of looking up what something means is a context switch that breaks flow and slows you down. It’s really inconvenient, which leads to problems. Better to replace c with context everywhere so you don’t need to look it up in the first place. Same is with why comments vs commits: it’s significantly more effort to delve through commits, even clear ones, than read a comment right there.
So what does this have to do with what comments? Let’s take a popular refactoring example: Extract till you Drop. The
replacemethod takes a few bits of time to understand and would definitely be helped with a couple of what comments. But what if, instead of comments, you refactor it to be “self-documenting” code? The author does that, creating six more methods in the process. It’s definitely easier to read each individual method than it was before.But if I’m not trying to understand the methods. I’m trying to understand the class. Now I have to jump all around
SymbolRefactorto understand it end-to-end. In fact, while doing that, I spent way too long looking forGetSymbolbefore I realized it was an external call. When I went back to the original class, that fact was instantly obvious. If I was doing a code review and was sanity checking the algorithm, I’d definitely prefer the first version + what comments than the last version.Why not both? My rule of thumb is to explain the why in the commits. Only if something seems counter-intuitive I’d add it as a comment. (So mostly no comments).
However I get the impressions most devs don’t have an easy way to traverse the history from the comfort of their editor. I can’t imagine living w/o Emacs’ vc-annotate
One important difference between commit messages and comments is that commit messages have a chronological context. We can talk about the previous solution in a commit message, e.g.
In contrast, comments need to make sense to future readers who may not know or care about the way things used to work. In this case we might have a comment like:
I agree; more concretely, a few of those extraction steps (e.g.
nextSymbol) break encapsulation, introduce sequential coupling and break thread-safety. Those problems aren’t specific to this code though, they apply to all “iterators” (which I think of as the “I want to use Java’s non-OOfor/instatements, and I’m willing to tear apart the remaining OO aspects of my codebase to do so” anti-pattern).Yes, the methods are private to the class; but classes aren’t the only unit of encapsulation/modularity/information-hiding.