Every Scout in the United States learns the legend of the “Unknown Scout.” In 1909, an American businessman, William Boyce, was lost in the fog in London (this was before the Clean Airs Act restricted the burning of coal, and London’s fogs were really more a noxious smog than a quaint low-lying cloud). A boy emerged from the fog and helped Boyce get back to his hotel. When Boyce offered a tip, the boy refused, explaining that he was a Scout and simply doing his daily Good Turn before disappearing back into the fog. Boyce was so impressed with the Scout ethic that he brought Baden-Powell’s “Scouting for Boys” back to the United States, thus launching the Scout movement in North America.
Like most good legends, this one has some holes in it. Apparently there wasn’t really a fog that day, and the boy just helped Boyce get across a busy street. A nascent Scouting culture already existed in the United States and Canada, founded by Dan Beard and Ernest Seaton, and in fact the Woodcraft Indians and Sons of Daniel Boone greatly inspired Baden-Powell; B-P’s version of Scouting would probably have made its way over the Atlantic without that helpful Scout. But like most good legends, it’s a useful one, and illustrative of the Scout spirit.
A SCOUT’S DUTY IS TO BE USEFUL AND TO HELP OTHERS. And he is to do his duty before anything else, even though he gives up his own pleasure, or comfort, or safety to do it. When in difficulty to know which of two things to do, he must ask himself, “Which is my duty?” that is, “Which is best for other people?”—and do that one. He must Be Prepared at any time to save life, or to help injured persons. And he must do a good turn to somebody every day.
Scouting for Boys, Robert Baden-Powell, 1908
Helpfulness involves offering up something that we have to someone who lacks it. In information technology, the thing that we have an abundance of is, of course, information. We have access to tons of data, and our daily bread is extracting, manipulating, and distributing that information in useful ways.
Simply providing information, though, isn’t helpful. Helpful information is specific, timely, and relevant. The Scout who helped Boyce (in the fog version of the legend) could have given a lot of information to the befuddled businessman. He could have told him that they were standing in the city of London, and that the fog was especially thick that day; a certain kind of Scout could also have told him the temperature and dew point, explained the effect of prevailing winds on the fog, and suggested that the composition of the fog was largely coal smoke and a North Sea low pressure system. All good, true information, but all horribly useless: the Scout would not have been helpful at all by giving those facts. Boyce needed task-specific information–how do I get to my hotel?–and that’s what the Scout provided.
As programmers, we need to be in the habit of providing the same kind of targeted information: to our managers, our business partners, and each other. A good place to start practicing that habit is in the code we generate:
Comment only what requires a comment, and strive for readability in your code.
We’ve all seen, and been guilty of, unhelpful comments in our code. An unhelpful comment isn’t necessarily a false comment; it’s just one that doesn’t aid in understanding the task the code is trying to accomplish. For example, a lengthy comment on the inner workings of SOAP and the implementation of a Jakarta HTTP client to negotiate an XML-RPC connection might be fascinating, but it has no place in the code itself. Tell me what you’re getting from that SOAP source, not how you’re getting it; if your code is clean, I can figure out how it works.
Commenting the obvious but skipping the difficult is another sign of unhelpful code. When I see source code where simple iterator loops and string parsing functions are heavily commented, but an obscure and obtuse method has no comments at all, I’m nervous; I suspect that the person who wrote (or copied and pasted) the code doesn’t really know how it works, either, and I start to wonder if those other comments hold water, either.
You can cut down your need for comments by writing readable code to begin with. One of the first places to start is with variable names. It’s all well and good to use throwaway names for purely instrumental variables–iterating over an integer called “i”, doing transient string manipulations on “s”. But if it’s going to persist for more than the scope of one method, or if it represents a business object, or especially if it’s going to be exposed in an API function someone else will use, then give it a real name. “Foo,” incidentally, is not a real name; nor is “bar” nor (as one of my Lotus Notes colleagues tended to name things) “chucky.” Since most modern IDEs offer type-ahead, and most modern languages don’t have onerous limits on variable name length, you can be verbose without wearing out your fingers.
As one who has both developed and maintained a lot of code, I’ve learned to see myself like the Tralfamadorians in Slaughterhouse-Five: a four-dimensional being stretching off into the future. When I make my code clear and well-commented, I’m not only helping my teammates now, I’m helping the future me who will forget the nuances of the code almost as fast as it was compiled.