Ch 4 Documentation and Commenting
The final goal of any engineering activity is some type of documentation. When a design effort is complete, the design documentation is turned over to the manufacturing team. If the design documents truly represent a complete design, the manufacturing team can proceed to build the product
—Jack Reeves, C++ Journal, 1992
Before graduate school, I spent a little time working with my mom on research into modeling cardiac drug efficacy, which meant diving into her code. Punch cards had an 80 character limit, some of this space was reserved for line numbers in her programming language of choice, FORTRAN. From years of writing under such restrictions, she rarely commented and used “interesting” names for her variables based on words she could remember and recall easily.
One time there was a dispute with her postdoc, who happened to be married to someone high up in the university hierarchy. Using this leverage, the postdoc, who had claimed my mom had stolen all her work, had the side of the administration and they locked both their codebases up during the dispute.
After many months, the administration unlocked the files and looked at them. The program had variable names after all my mom’s family members: KEN (my brother), TERRY, SEUNG (dad), TERESA (herself) and variations (KT, MOM, DAD, etc.). In the postdoc’s code, there was not even a single file—she had deleted all of it in a fit of anger and forgot over the intervening months. Needless to say, my mom won in the end.
I guess if you are ever worried about your stuff being stolen, leave your stamp somewhere in the code. Now, I wouldn’t recommend you name variables after family members. Instead, I suggest you comment liberally.
Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live. Code for readability.
—John F. Woods,comp.lang.c++
Recently, over brunch, a recruiter friend of mine mentioned that she had a candidate who hailed from one of my former companies.
“I asked him if he had ever heard of ‘Terry Chay.'” she said.
“Oh, that was so long ago, I doubt…”
“But he had! He said that he sees your name all over the codebase. ‘I learn a lot from looking at it,’ he said, ‘Sometimes, it takes a while to understand why he did what he did, but his solutions are elegant.'”
My girlfriend asked, “How did he know it was you?”
“Oh, I comment a lot!” I replied.
At the time, I hadn’t worked at that company in over eight years. The website I worked on didn’t even exist anymore. But be sure to use comments to document your code. You will make life better for the untold people who might have to depend on it.