fornax.net

From Joel on Software:

“Shipping is a feature. A really important feature. Your product must have it.”

Too right!

From the Signal vs. Noise blog:

“There’s a lot of talk about change being hard, but sometimes it’s harder to keep your mind than change your mind.”

I couldn’t agree more. I’ve seen the fact that a development team is working in an “agile” environment used as an excuse for not making a decision so many times, it’s crazy. The argument usually goes along these lines: “It’s impossible to know what the right decision is, so let’s just make any old decision. We can always change our minds later. After all, we’re ‘agile’.”

I just want to scream when this happens — just because you use an Agile development process is not an excuse for being lazy in your decision making. Think about the problem, discuss it, mull it over, sleep on it, and start all over again if you need to. But be confident, when you have made your decision, that it’s the right decision.

Yes, you may need to change the decision later, when circumstances change or new information comes along ; but at least start out with confidence, and maintain that confidence until you find a compelling reason to change course.

From the Agile in Action blog:

“Quality goes down and technical debt increases with every corner cut. When prioritized against the next feature promising to deliver business value, debt never gets repaid.”

“[Business decision makers] understand the cost of goods returned, the cost of rework, and the loss of customers but they choose to remain ignorant of the fact that these are typically the consequences of not valuing quality.”

How very true!

Joel writes:

“The biggest surprise was how much work it took so that every user sees things in their own time zone.”

Oh yeah, I hear you. Now imagine that your software has to do that not because you are hosting it for your clients all over the world, but because your clients all over the world are hosting it themselves, but on boxes controlled by someone else, in a different part of the world to where they are. Also imagine that these hosting companies refuse to set up the box in the timezone of the client.

Now, try and get your software to work in five different versions of PHP, with major differences in how timezones work. Deal with the fact that the hosting companies haven’t configured the PHP timezone correctly for the server’s timezone either.

And then throw in some bugs as well.

Joel has it easy.

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.