Monthly Archives: July 2008

Staking my claim

Well, my first gig at the new job is well into its second full week, and I’ve got to say it looks like I’ve got interesting challenges ahead. For one, I’m introducing unit testing (and TDD) into a codebase that was written without tests in mind. Fortunately I’ve read (and re-read, and then re-read again for good measure) Michael Feathers’ Working Effectively with Legacy Code. It’s a great source of working techniques.

I have to say, I find quite a bit of satisfaction in conquering an area of code, marking it as mine and covering it with tests. The small victories slowly turn into larger ones, and eventually I may even feel safe making changes.

I was particularly pleased when I had written the bits of a new feature (pluggable in place of an equivalent, pre-existing one) in a TDD way, and then after a while of slow but steady progress, the code rapidly converged to a fully working and more or less finished state. I had the benefit of knowing that this is the way it works, but my guide from the customer company was surprised and delighted.

There’s a lot of work to do, but I’m pretty confident. :)

Blanket statements

Looking back at my last post on documenting code, particularly the part which I originally posted as a comment, I realized that it was pretty much exactly what Joel Spolsky was talking about in the latest Stack Overflow podcast:

[…] I didn’t write defensively like I usually have to, qualifying it with every possible e-mail response I could ever get. And so, it actually led to quite a lot of people saying, “No, that’s wrong! […]”

[…] over time you start to realize that there are actually all kinds of weird shades of grey, and slightly different variations on things, and it becomes harder and harder to make absolute statements that are interesting. Because, if I were to write an intellectually honest blog post now, it would be like, “63% of the time–you’re probably in a situation, where, 63% of the time, you should do A, and the rest of the time you should do B. Here’s some cases where you would do A, and some cases where you should do B, and the whole thing would just be too mushy.

I guess the original text where my comment was posted was this sort of absolute statement, and my comment would fall into the “mushy” category, unfortunately.

There’s no punchline to this observation, though, which is kind of a drag. I feel like I should end this post with an insightful conclusion or at least a witty remark, but right now, I got nothing. 😛

There’s no substitute for good judgement

Another great, flameworthy topic at Girl Developer: Documentation: A Sure Sign of Garbage Code. The title is a bit misleading though, as the problem is not documentation but comments. If you’ve got non-xDoc comments all over your code, you’ve got issues.

To save myself some typing, here’s my take on the issue, quoted (sans intro and outro) from the comments:

in my opinion, documentation is good. Comments on the other hand, may be good *or* bad. Comments can quickly become something that’s definitely not documentation.

When the WHY of something is not obvious, it should be explained in a comment.

When the HOW of something is unclear, the code should preferably be clarified. IF that’s not possible, or there is no time or some other constraint prevents it, it should be explained in a comment.

Public APIs should be documented with the appropriate documentation comment facility.

It should not be necessary to document the WHAT. If the class and method names are so unclear that you need to do it, you’ve got other problems. But as always, there are exceptions to this rule. :)

If you have the luxury of having others on your team, you could try asking them to explain what your code is doing just by looking at it. If it doesn’t match the way you know it works, you need to either clarify it or document it better. But the ground rule still is, as always, there are no absolutes. In these matters, you should strive to make an informed decision based on your own experience. Don’t let anyone (least of all me) dictate the way you do things.

Unless of course you happen to be on my team, in which case forget what I just said and do as I say, goddamnit!

First work day with some actual action.

General impression: great co-workers. You know, actual, competent programmers, and people who are enthusiastic about unit testing, and stuff like that.

Of course, this is the beginning of the honeymoon period of the new job, we shall see how things look after the first couple of months. :)

First gig is to integrate bits of an existing application to parts of larger infrastructure. All in all, things look good. I wonder what the monster lurking in the closet will be. 😛

Quick update

Holidays over, starting at new job (home office for now). Things picking up in the next few days. Last month’s Vista crashes turned out to be caused by ReadyBoost, specifically the driver for the flash chip on the hybrid HD. Disabled the whole thing for now, since the driver update didn’t apparently fix it.

More to come in the next couple of days.

Edit: forgot to mention, I turned in the forms necessary to enroll in the University. Forgot to bring along a copy of a receipt though, should mail that in in the next couple of days.