I can’t sleep, so I figured I’d wade into the inline documentation debate.
Travis states that programming languages are declarative, so code, along with associated unit tests are enough to define what the code does, as well as provide examples of how to use the code.
Well, I agree with that.
However, that doesn’t mean that inline documentation is therefore a “bad thing”. Tobias has pointed out a couple of reasons why that’s the case. I can think of a couple more, too.
Firstly, bugs.
Just becuase you’ve written your code, and you’ve written unit tests doesn’t mean the code is bug free. It should be, if your tests are good, but how much do you want to bet on that? Sometimes the unit tests you’ve written (so far) haven’t made the code bug free. It does happens. So, you extend your unit tests to cover that bug, and then you fix the code. No big deal.
But have you ever tried doing that with someone else’s code? I know that on many occasions, I’ve been using an external library, and thought I’ve found a bug. So, I’ve sent off a bug report and a patch, only to be told, "No, that’s how it’s supposed to work." How was I meant to know?
If you define "what the code does" as the same thing as "what the code should do", then there’s no such thing as a bug. Of course, that’s not really the case, is it? In fact, "what the code does" is only the definition of "what the code does", not "what the code should do".
That’s what inline documentation is for. A brief description of what the code should do, so that it’s possible to take a stab at working out if what the code does is the same as what it should be doing.
Secondly, understanding.
I’m not talking about helping other developers understand your code. As has been mentioned in the two articles above, tutorials, unit tests, decent method naming conventions, code layout, etc. as well as reading the code itself are probably more useful in helping developers new to your code in coming to terms with your code base. The inline documentation will only help those developers once they’ve come to understand it a little, and they want a quick reference later on.
No, I’m talking about your understanding of the code you’re writing.
When I was at Uni, I found that one of my most valuable exam techniques when I was faced with a tough question to answer in a short amount of time was to ask myself, "How would I explain this to my Mum?" By boiling the problem down into the simplest bits I could think of, and by approaching the problem from a way that was different to how you would explain it to an expert in the field, I’d often find that I’d come to a realisation of the really important part of the problem much faster than by trying to deal with the complex whole.
I find this works really well with programming, too.
Sure, I can bash out a method that does what it needs to do pretty easily. But when I write doc blocks, I find that the process of having to come up with one or two sentences that explain what the code is supposed to do really help me focus my attention on the point of the code, and to ensure that the code is doing what it needs to. I can’t possibly remember how many times I’ve written a doc block, and suddenly gone, "Oh, wait, what about…?".
So, as Travis says, if your code is so complex that you have to document it in English, then yes, it’s probably time to refactor. But that doesn’t mean inline document is bad – there’s some real benefits to documenting your code.
One thing I would add here is that the unit tests – when following a TDD or test-first approach – answer the question “what should the code do?” Using a contrived example, if you have a function called add() and your test verifies that 2 + 2 equals 4, the the function body should be: return 2 + 2;
That said, I do know several developers who’s mind works better writing out a quick docblock to start coding. It start their mind on the “oh wait, what about …?” path. It’s what works best for (the rhetorical) you. I tend toward tests because that’s something I can reproduce later.