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
More importantly, it tells you this when it’s happening. Let’s say, God forbid, that Wesley Crusher destroys the ship in a fit of teenage angst and all we find of the ship is the jettisoned Captain’s Logs. Would you rather the last few entries say:
Captain’s log, Stardate 51734.1 “Wesley Crusher has rejoined the ship after an extended stay with the Traveler. In the intervening time, he has grown angrier. Dr. Crusher is relieved to see her son, but concerns about his mental stability remain. I’m asking Dr. Pulaski to run a full scan on him to be certain.”
Captain’s Log, supplemental. “Dr. Pulaski has run the scan, and determined that there is a creature of unknown origin inhabiting Wesley Crusher. In his more lucid moments, Wesley believes he received the parasite during a visit to Risa’s notorious South Pole.”
Captain’s Log, supplemental. “The parasite has taken over Wesley crusher completely, and has used the knowledge of the Enterprise to jettison the Warp core and shut down life support. There is currently no way to get off the ship. This will be my final log as captain of the Enterprise. Her ship and crew have served well, and are in keeping with the finest traditions of Starfleet. I am transmitting this log on subspace Starfleet Command, Priority One.”
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’.