There's a thread going around about comments in source code. Christian said:

Not all comments are bad. But they are generally deodorant; they cover up mistakes in the code. Each time a comment is written to explain what the code is doing, the code should be re-written to be more clean and self explanatory.

Oliver Steele responded:

Comments are an escape hatch for expressing everything about the program that the programming language can't.

Opening shots notwithstanding, the essays agree more than they disagree. Both decide that there are lots of important uses for comments. In my experience, it boils down to a simple distinction:

Code says what to do, comments say why.

The comments Christian is railing about in his post are probably comments that tell you what is happening. We've all seen the classic:

i++; // increment i

This is bad because the code already described what is happening, and the comment is simply describing it again. No new information has been added to the system. Of course in the real world, the examples are usually not so blatant.

If you find yourself writing comments that describe the "what", think about whether you have an expressive-enough coding style, or whether you need richer primitives, or a more directly applicable framework. There may be ways to change your coding so that the "what" is adequately covered by the code. Then you can focus on the "why" in your comments.

BTW: Christian also covers the writer's difficulty of understanding their audience from a commenter's point of view in his followup post.

Seems like I've had a lot of discussions with friends about resumes recently (really: I'm not looking for a job). When my engineer friends let me see their resumes, my comments are usually the same:

• Don't be shy about selling yourself.
• Concentrate on things that set you apart from your peers.
• Describing yourself is more important than describing your work.
• Try to break out of the traditional "I did this, then I did this, then I did this" style. Find a way to describe yourself that goes beyond the sum of your tasks.
• Don't write paragraphs when a terse list will do.
• Don't include motherhood statements. You wouldn't put "I showed up for work every day" on your resume, so why put "I followed good engineering practice"?

For example, look at Kevin Marks' resume. The first thing that jumped out at me reading through it was the "Products Shipped" section. Of course! That's a key piece of information that employers like to see. Splitting it out into its own section is a great idea. Along the same lines, a headhunter told me a long time ago to add a section at the top of the resume called "Qualifications" that goes beyond skills or experience, and just describes you: why should an employer hire you?

Another thing that jumped out at me from Kevin's resume:

I also maintain an active presence on Apple and other mailing lists — Ben Waggoner tells me that the best way to get the right answer for a QuickTime-related question is to add "Kevin Marks" to your Google query.

This is unconventional, and boastful (though the "Ben tells me" preface softens it), but also honest, attention-grabbing, and of interest to employers. Remember: your resume is an ad for you. If it doesn't sell you, nothing else can.

Remember Matrix Ping-Pong? My mom used to live in Japan and it turns out this show was a favorite of hers. She gave me the details:

Kasoh Taikai (Masquerade Contest) is a wonderful show. They have it about 2 or 3 times a year, always with the same beloved old comedian (sort of Milton Berle-ish) as the MC. All the contestants are amateurs — families, or school classes, or housewives, etc. They think of something to imitate, using their bodies mostly and homemade improvised costumes. Some are horrible and some are quite fantastic, but all are unexpected and inventive. After each act, the audience (or judges? I forget) evaluates them and the really bad ones are bong-ed out (a big carnival gong is used, with each vote making it go higher). There are about 20 acts in each program, and at the end big prizes are awarded to some of the un-bonged ones.

I think the ones on their site are the one (or two or three?) winners from the last few years.

After reading about the new version of TweakUI on Raymond's blog, I downloaded it to see what new goodies there were. The one that caught my eye was command prompt selection coloring. Enable it, and you can select text in a command prompt window, hit Ctrl-0 through Ctrl-9, and the color of the text will change permanently. It's like having a highlighter for your confusingly Matrix-like text windows full of server gibberish.

Raymond Chen has a fascinating new blog. He's a developer at Microsoft, and although his blog in on gotdotnet.com, it's not about the Latest Thing from Microsoft at all: it's mostly about good old hardcore Win32 programming, and internals trivia about Windows. It's full of interesting insights and behind-the-scenes details. Plus, he's one of the developers of TweakUI.

Tangentially: I can't believe we're still putting up with calendar-based archives. Raymond's site is a perfect example. The old entries are just as interesting as the new ones, but impossible to get to. I have to choose dates off the calendar, and when I wanted to scroll back through the whole history, I had to do an awkward tiptoe through the calendrical tulips to find the entries day by day.

During these days when Mars is closer than it has been in 60,000 years, everyone wants to look skyward for the red planet. But for those of us in urban areas a good view may not be possible (houses, trees, light pollution, and what-not).

Celestia to the rescue! This space simulator has all the obsessive detail you could want, from the texture of the Earth, to every moon in the solar system, to distant galaxies. There are even contributed databases of ficticious worlds.

On a side note: the desktop icon for Celestia looks an awful lot like the one for Eclipse, and ended up right next to it:

We've been using Perforce for almost four months, and it's gone very smoothly. Unfortunately, we had a perplexing problem the other day: how to gain admin privileges if no one at the company already had them.

I sent an email to Perforce support, and within an hour I had an answer: detailed instructions that solved the problem. Fabulous. Highly recommended.

Esther Derby finds inspiration for mental blocks from Ursula LeGuin:

When action grows unprofitable, gather information. When information grows unprofitable, sleep.

By the way: Esther's blog is a good source for opinions and discussion about the human side of work. For example:

• How to ask for help
• You really can't do more with less
• What project managers do
• Advice on writing

If you are a manager, or just an engineer dealing with people stuff, take a spin around Esther's blog: it couldn't hurt!

Some people really have too much time on their hands: Paul McCartney Really Is Dead: The Photographic Evidence.

This has been around for a while, but I just came across it again, and loved it again: Flame Warriors.

When your ire is raised, which warrior are you?

A friend and ex-co-worker of mine has recently started a blog: Bob Congdon. We worked together on the Domino web server, and he's got the perfect blogging personality: a flypaper-like retention of the sort of semi-useful technically interesting stuff that makes blogs what they are.

If the last month is any guide, his will be an interesting blog (although there was a gap of more than two years between his first post and his second!).

Something happened recently which has caused me to think a lot about engineers and their people skills, and the care we take of each other. A co-worker of mine was let go because of performance problems. I look back on the situation, and wonder what could have been done differently.

Over the course of my career, I've seen lots of problems with engineers and their dealings with each other. I've written up some ideas, and they all boil down to one radical concept: Engineers are people.

We've all heard that glass is a liquid, not a solid, appearances notwithstanding. We've been told that in fact, glass is glacially flowing all the time, and that old window panes are thicker at the bottom than at the top because of centuries of flow.

Well it's all wrong.

Just when you thought there was nothing truly useful on the web anymore, Dan Cederholm comes through with The Spoon Trick.

If you ever begin to fall under the misconception that the beautiful people you see in magazines are really that beautiful, and that somehow the rest of us are lowly troglodytes in comparison, visit Greg's Digital Retouching Portfolio, especially the bikini and blonde images.

Google has done it again, with Google Calculator. Want to know what a mathematical expression evaluates to? Ask Google: 7 * 11 * 13. It can do it with words too: two plus two. Units of measurement are no problem: radius of earth in miles or speed of light in furlongs per fortnight.

The thing that amazes me about this is not how useful it is, but how Google has implemented it as part of their standard search. To make this work, they have to sniff out calculations in search terms. This determination comes up with yes, no, and maybe. You can see this based on whether Google gives you search results (gram), calcuation results (pound in grams), or both (pound). Because Calculator is not a separate page, but a regular search query interpreted differently, Google has to run this calculation sniffer on every search.

I know Google has an enormous server farm devoted to making searching fast, but to have that much confidence in a new feature, and one that will only kick in occasionally, is inspiring. Lesser developers would have moved this off to a new page to protect their baby, but would have had a less useful feature. The cool thing about Calculator is not that I as a geek can go to Google knowing that it will do a calculation. The cool thing is that ordinary people who don't know any better will get the answer to their question.

As it happens, about a month ago, I really did want to know about tablespoons in a cup. I typed a query into Google to get the answer. If Calculator had kicked in and showed it to me "magically", I would have fallen out of my chair and made offerings to the Google gods. Of course, in the final irony, being a geek, I knew that "in a" were useless words in a search query, and searched on tablespoon cup conversion, which doesn't invoke the magic of Calculator.

My son came to work with me for a few days, and one of the things we talked about a lot was the Mirror Project, the collection of user-submitted self-portraits in mirrors. Here are some we came up with:

The picture we were really trying to get though, was us whizzing down the highway, reflected in the shiny hubcap of a truck. We finally got a pretty good shot, but it wasn't accepted by the Mirror Project, I think because you can't really see a person in the picture. I still like it though:

Eliyon's CorporateAlumni is an interesting data mining exercise: scan all the press releases and other corporate communications on the web, and build a database of who has worked where. It's a concrete example of how hard it must be to get data this way: My entry seems to list me as currently working for either NotesPeek or NOTES.INI setting. Also, it seems there used to be a guy at Lotus named Lotus SmartSuite.

And was Nikita Khrushchev really a founder of Lotus Cars? I did not know that.

Two blogging song parodies:

• The Day the Blogging Died
• We Didn't Start the Weblogs

What is Copy Shop? Is it a spooky meditation on the repetitive nature of boring jobs? A cautionary tale about the power of technology to overwhelm us? A haunting parable about individuality and the difficulty of standing out from the crowd? A visual essay about the nature of cinema? A remarkable short film produced on a photo-copier? All of the above? You decide.

For those in the US going on vacation (as I am about to do), did you know that the US Postal Service will let you request a hold on your mail over the web? USPS Delivery Services gives you a simple form, and presto! No mail for a week. Long gone are the days of awkwardly meeting your neighbors to ask them to take your mail in. By the way: there's nothing in the form to determine that you are requesting a hold on your own mail. More malicious minds than mine would see a prank in the making...

I wrote a while ago that I was going to try Eclipse with some new Python add-ins. It was not an entirely smooth ride, for two reasons: one, the python add-ins are very bare-bones at the moment, and two, Eclipse has got to get over itself.

» read more of: Eclipse impressions... (15 paragraphs)

I swim for exercise, and have watched smaller, slighter swimmers than me zoom past me in the next lane, and have wondered what they are doing right. I've never been formally trained in swimming, so I know I have a lot to learn. I found Articles on Stroke Technique, a series of chatty articles describing good swimming technique. I read them, went to the pool, and swam about 10% faster than usual.

The main points:

• Try to have as long and slim a shape in the water as possible.
• Use your arms to transmit torso power to the water, rather than to pull yourself through the water.

As a result of recent personal entries, some people have been coming here who are new to blogs, and have been asking "what's a blog?". So I've tried my hand at answering the question.

Have you ever thought that programming tools like VB and wizard-laden IDE's were designed to allow even the least-skilled developers to make forward progress? You may be right. Check out Primate Programming Inc: The Evolution of Java and .NET Training.

Google now has a new feature: Synonym searching, whereby pages will be found that contain synonyms of the word you enter in the query. Put a tilde (~) before the word in the search, and synonym matching is enabled.

Lively discussion is already beginning about how it works under the covers. Is there a big thesaurus behind it, or is Google somehow tapping into its own gigabase of data to decide on synonyms? From the waxy.org discussion is this tidbit arguing for Google-mining providing the raw data: Bush is a synonym for Gore.

As a reward for getting Reactor online, I played a game of mini-golf. I was one over par for the course. Which, come to think of it, was like Reactor itself: fun, some parts competent, some parts embarassing, and it took a little longer than I thought.

I've replaced my commenting system. Enetation was good, but a little rough around the edges, and a little flaky (did you notice that for a while the (react) link on the Firebird entry below said "(undefined)"?). And as I mentioned in my original post about enetation, I would rather have hacked something together myself. So now I have. Reactor (as I've called it) is online. You shouldn't see much difference, but let me know if you do!

Details: it is written in PHP using MySQL, and I've imported all the old comments from enetation, so all of the comments are now in Reactor.

Frans Bouma rants about Edit and Continue. He claims it encourages bad debugging style. I wouldn't go that far, but I don't use Edit and Continue because I don't believe in it. Not "don't believe" as in "I think it is poor practice", but as in "I think it is impossible".

Now of course I know the feature is implemented, and many people use it, and they are happy with it, so it must work for them. But it doesn't fit my mental model of how software systems can operate. When I have tried it, it either works, which seems miraculous, or it doesn't, which is disappointing. So I don't believe in it, and don't use it.

For those that may not know: Edit and Continue is a feature of Microsoft development environments where a running program can be edited, recompiled, dynamically patched, and execution continues.

In case you haven't heard, Mozilla Firebird 0.6.1 is now available. It's a great browser — try it.

I use Microsoft Visual Studio .NET for C++ work at work, and it is very powerful, and does lots of cool things. (Although, there are two things it doesn't do as well as previous versions did: the class browser won't show derived classes, and two documents of the same type can't have different tab settings). One thing I wish it did better was finding strings in files. It finds them just fine, but there's no way for me to keep the results: the next find overwrites the last results. I wanted to change that.

» read more of: DevStudio persistent find... (11 paragraphs)