Comments in Clean Code? Think Documentation
Editorial Note: I originally wrote this post for the SubMain blog. You can check out the original here, at their site. While you’re there, take a look at GhostDoc for your documentation needs.
Second Editorial Note: I recently appeared on the Ruby Rogues podcast and was interviewed by Paysa. If you’re interested, check both of them out!
Notwithstanding some oddball calculator and hobby PC hacking, my first serious programming experience came in college. A course called “Intro to C++” got us acquainted with arrays, loops, data structures and the like. Given its introductory nature, this class did not pose a particularly serious challenge (that would come later). So, with all of the maturity generally possessed by 18 year olds, we had a bit of fun.
I recall contests to see how much application logic we could jam into the loop conditions, and contests to see how much code could be packed onto one line. These sorts of scavenger hunt activities obviously produced dense, illegible code. But then, that was kind of the point.
Beyond these silly hijinks, however, a culture of code illegibility permeated this (and, I would learn later) other campuses. Professors nominally encouraged code readability. After all, such comments facilitated partial credit in the event of a half-baked homework submission. But, even still, the mystique of the ingenious but inscrutable algorithm pervaded the culture both for students and faculty. I had occasion to see code written by various professors, and I noticed no comments that I can recall.
Professionalism via Thoroughness
When I graduated from college, I carried this culture with me. But not for long. I took a job where I spent most of my days working on driver and kernel module programming. There, I noticed that the grizzled veterans to whom I looked up meticulously documented their code. Above each function sat a neat, orderly comment containing information about its purpose, parameters, return values, and modification history.
This, I realized, was how professionals conducted themselves. I was hooked. Fresh out of college, and looking to impress the world, I sought to distinguish myself from my undisciplined student ways. This decision ushered in a period of many years in which I documented my code with near religious fervor.
My habit included, obviously, the method headers that I emulated. But on top of that, I added class headers and regularly peppered my code with line comments that offered such wisdom as “increment the loop counter until the end of the array.” (Okay, probably not that bad, but you get the idea). I also wrote lengthy readme documents for posterity and maintenance programmers alike. My professionalism knew no bounds.
