Stories about Software


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.

Read More


Automate Your Documentation

Editorial Note: I originally wrote this post for the SmartBear blog.

Few things, I’d say, strike boredom into the developer heart faster than the subject of documentation.  Does anyone out there really just love wrapping up development on a feature and then cranking out a Word document with a bunch of screen shots and step by step instructions.  Or, perhaps you fancy the excitement of pasting a legal header above a class you’ve just written, and then laboriously documenting all of methods, variables, and function parameters in the class?  If not that, how about the thrill of going back and updating comments that no longer make sense after the code has changed?

I suspect I don’t have a lot of takers at this point.

Documentation is boring, at least for the overwhelming majority of us.  After you’ve built a thing, you want to go build another thing — not rehash in laborious detail what you just did.  And yet, documentation is essential for communicating across time and teams to other people.  Your users will need documentation.  Future maintenance programmers need documentation.  Unless you’re going to be around in perpetuity to handle all that comes, you need to leave some sort of persistent knowledge transfer vehicle.

But that doesn’t mean it has to be tedious, repetitive, or boring.

Repetitive labor offers a certain counter-intuitive appeal, since it creates a “pain is gain” feeling of diligence and accomplishment when complete  But don’t be fooled.  People make many sloppy mistakes when doing repetitive tasks and drudgery is a terrible use of company money when you’re collecting a salary as a knowledge worker.  As people in the software industry, we earn a living automating grunt work out of existence, so let’s take a look at how we can help ourselves when it comes to documentation.

Read More


What Technical Documents Should You Review?

Editorial Note: I originally wrote this post for the SmartBear blog.  You can check out the original here, at their site.  While you’re there, have a look at the posts by some of the other authors.

If you’re anything like me in your programming proclivities, there’s a kind of singular impatience that leaps into your mind around the subject of documentation.  On the consuming side, whether it’s an API or a product, you have a tendency to think to yourself, “I don’t want to read about it, I just want to start hacking away at it.”  On the flip side, when it comes to producing documentation, that seems an onerous process; you’ve already finished the work, so why belabor the point?

Those are my natural impulses, but I do recognize the necessity for producing and consuming documentation surrounding the work that we do.  Over the years, I’ve developed strategies for making sure I get it done when it needs to be done.  For instance, even as someone who makes part of my living writing and teaching, I still segment my days for the sake of efficiency; I have writing days and I have programming days.

In order for this work not to get shortchanged in your group, it’s important to develop similar strategies or commitment devices.  The work needs to get done, and it needs to get done well, or else it won’t be useful.  And peer review is a vital part of that process.  After all, you create process around peer review for code — the developers’ strategy for sanity checks and spreading of knowledge.  Doesn’t it stand to reason that you should also do this with the documents that you create around this process?

Let’s take a look at some documentation that your group may be producing, and explore the idea of having peer review to go along with it.  We’ll look at an answer to the question, “what technical documents should you review?”

Read More