Captain’s log, Stardate 43539.1. We have moved into orbit around Bre’el IV. With the assistance of the planet’s emergency control center, we are investigating a catastrophic threat to the population from a descending asteroidal moon.”
“Captain’s log, supplemental. We are no closer to finding a solution to the deteriorating orbit of the Bre’el moon, but with the arrival of Q we now have a good idea of the cause.”
“Captain’s log, supplemental. We have sustained light damage from an attack by an alien species known as the Calamarain. They apparently have a grievance with Q – no doubt one of many lifeforms that do.” (TNG: “Deja Q“)
The Captain’s Log takes you through the high notes, letting you know three things:
- What happened
- What’s happening now
Captains Log, Stardate 51734.1 “Wesley crusher came onto the ship today and proceeded to shut down life support and jettison the warp core. There’s no way to leave the ship.”
The first one, of course. It sounds better. it’s more complete, and in case your ship is found adrift with all crew dead, at least someone has an inkling of what happened to you.
Just like in code.
You fix a problem, you go on vacation or win the lottery, or quit. As soon as you step off the plane in Tahiti, there will be a bug with what you fixed. The programmer tasked to fix this bug is going to want to know what you did. He has source control for that; but he’s also going to need to know *why* you did what you did. What alternatives did you consider?
I’ve written about this before.
The bug report is your chance to concisely list the relevant issues with a bug, how you are going about fixing it, and most importantly, what didn’t work. Maybe I’m senile, but I can’t remember what I fixed 6 days ago, let alone 6 weeks ago. The bug report helps me keep a running log of what I’ve tried and what I haven’t. In instances where it doesn’t make sense to put it into a defect tracking system, I keep a personal notebook. It goes with me everywhere, and it contains details on any solution I’ve ever tried. It’s my own personal Captain’s Log, and privately I call it that.
If you’re just publishing Changeset numbers and the word fixed in bug reports, you’re doing your teammates a disservice. Programming is hard enough as it is, don’t make it any harder by not ‘showing your work’.