“Why” documentation - in code? in tests?
With one major exception, I’m one of those “if your code needs documentation, it’s not written right” people. The exception is code that answers the question “Why do that instead of this other obvious thing?” If I’m answering a “why” question with a comment, I always wonder whether the comment should go in the code or in the tests.
As an example, consider an app I’m working on. In response to a user request (picking a menu item), a potentially long-running network transfer starts. What the user sees while that’s going on is that the app switches to the tab that normally displays the table of data she’s asked for, that table has been erased, and there’s a progress indicator spinning there.
Getting that to work is more complicated than you might think. Let’s pretend you’re trying to understand it.
The code behind the menu item posts a notification:
The DirectoryController’s initialization declared that this method gets that notification:
The RemoteDirectory also fields the notification. It looks like this:
First question: do you think the comment is helpful? If not, should I also explain that the Savon SOAP library doesn’t (seem to) allow asynchronous operation? Should I explain that RubyCocoa doesn’t allow threading, so I can’t invent asynchrony myself?
Second question: Would you rather see the comment here, in the code, or in the tests? Here’s the test of the load method:
Does the test name reduce or eliminate the need for the comment? (I would normally be using shoulda and assert2.0 here. I’m not because the project was originally in MacRuby, which didn’t handle them at the time I switched to RubyCocoa.)
If you think the name helps, does that suggest I should change the name in the product code to something other than load? What?
June 1st, 2010 at 1:40 pm
I think this is a tool issue. If I could see both the code and the tests for that code linked intimately, I think having it in tests would be great. I don’t have that tool, so having some sort of “why” in the code I think would be useful in telling me that there is something useful and out of the ordinary in the tests that I really should go read.
Brief description in code, more full description in tests. Keep the description in the code brief so it is less likely to grow out of date, and use those tests…
– bab
June 3rd, 2010 at 9:22 am
Tim Ottinger says:
I wanted to comment, but that logging in thing gets in the way.
My philosophy is reflected here:
http://agileinaflash.blogspot.com/2009/04/rules-for-commenting.html
I think that the comment on deferred handling helps, but is kinda wordy.
It doesn’t upset me if it’s in the tests. I look at tests, especially
if the code is doing something unusual. I like it when the tests give
me some kind of enlightment (I’ve seen that avoid enlightenment at all
costs).
I think it’s not a big deal. I am more likely to encounter the odd
behavior in the code first, so that gets 9.5 points of ten, and the
comment in the test gets a 9.4 of 10.
It’s not even 3/10 v. 7/10. It’s a narrow thing.
June 3rd, 2010 at 9:23 am
Danil Suits:
I have no idea whether commenting the code or the test is right, in the sense of a Platonic ideal.
But I have difficulty believing that a comment in the test works as well as a comment in the code.
Consider this comment, “We have to use ballbearings because the fetzer valve jams on Solaris,” in the context of a developer who is working on the code in a windows development environment.
Question: how many passing tests is the developer supposed to read looking for a comment to tell him that a particular refactoring is a bad idea?
My guess is that any number greater than zero is impractical, which means this developer is going to commit his refactoring before he discovers that it re-introduces a problem downstream.
June 6th, 2010 at 2:10 pm
I should say as long as the comment is not explaining what the code is doing, then the comment’s value should be re-considered. From duplication point of view, those what is happening comments are like duplications in code and is better to be merged into the code.
On the other hand, as much as I agree commenting what the code is doing is a bad idea, we should also face the fact that most(yes, I’d say over 80%) of our fallow programmers are not competent enough to write clean, self-explanatory codes. And forcing them(us) to write comments seems to be a easier task than teaching them how to code, especially to the managers who still believe programmers are code-labors. Even though most of the “bad” programmers are also bad comment writers, reading their comment is much easier than reading their code, even though the later might tell truth and comment might lie…