Comment your damn code!!!

“Any fool can write code that a computer can understand. Good programmers write code that humans can understand.”
— Martin Fowler

When I was a computer science major in college, I had professors who used to dock points if my code wasn’t documented.  It didn’t matter how well-written my code was, and it didn’t matter how well my code worked.  If I didn’t include comments to describe my code, what my variables were, why I used certain functions and coding techniques, a project that could’ve gotten an A grade instead got a B.

That memory came back to me this evening at our SQL user group meeting this evening.  Our guest speaker was Jen McCown, who gave a presentation called “T-SQL’s Hidden Support Feature.”  (A description of her sessions can be found here, and I found a SQL Saturday link to it here.)  Her presentation talked about a feature included with T-SQL (and just about every language imaginable).  It is guaranteed to improve how people handle, develop, and maintain code, and it costs nearly nothing to implement.

What is this miracle feature, you ask?

Code comments.

Simply commenting code can save developers lots of headaches and development time.  It can provide an explanation of how and why code snippets were used.  It can describe variables, what they’re for, and how they’re utilized.  It can describe program structures that help in debugging and maintenance.  I even remember a comment to a SSC forum post by Jeff Moden who mentioned the return on investment of commenting code.  It also reminded me of Steve Jones’ article about how important it is to comment code.  I believe Jen’s presentation should be required for anyone who writes code.  The benefits for commenting code are endless.

Commenting code is probably one of the simplest and most useful, yet most underutilized, methods of documentation.  I’ve mentioned time and again about how documentation gets no respect in technology, and yet too many developers still refuse to do it.  Jen’s presentation was a reminder of how important it is to document code; in fact, she also mentioned some points that didn’t occur to me.  For example, documents such as Word, Wikis, or Confluence can get lost, misplaced, or buried.  Code comments, however, stay with the code; it cannot get lost or separated from the code.  (There were several other points she mentioned as well, but it’s her presentation, not mine, so I don’t want to take away from it.)

When I was in school, I was docked points when I didn’t comment my code.  Sometimes, I think developers should be docked pay if they don’t do so.  Commenting code is the simplest, yet most effective tools around.  So you want to be a better developer?  Then comment your damn code!

Advertisements

Speaking near Beantown

sqlsaturday-logo

I got an email last night announcing that SQL Saturday #813 Boston — BI Edition has been scheduled for March 30, 2019.  I went ahead and submitted my presentations.

Because the Boston Microsoft office (despite the name, it’s actually in Burlington, MA, about twelve miles northwest of Boston) is a smaller facility, events such as SQL Saturday tend to be smaller; it’s more difficult to be accepted as a speaker, and a wait list for attendees is not uncommon.  Nevertheless, if I am accepted to speak at SQL Saturday #813 (far from a sure thing), that is potentially three trips I’ll make to Burlington within a span of seven months.  I am already scheduled to speak at SQL Saturday #797 on September 22 (a week from this Saturday as I write this) and at a New England SQL User Group meeting on February 13.  SQL Saturday #813 would make it trip #3.

Despite the fact that the Boston area tends to be hostile territory for a Yankee fan like me, I look forward to my upcoming trips.  I’m hoping to make it three trips in seven months.

Hope to see you there!