Often, you hear “code comments” and “code documentation” used at least somewhat interchangeably. ?Perhaps the idea of code documentation has a little more formalism to it, in passing. ?And code comments may cover a bit less ground.
But still, I hear the terms serve as synonyms for one another. ?And I hear this in particular when it comes to the actual construct of code comments — meaning, literally, the feature of compilers and interpreters that allows you to say, “Disregard everything after these two slashes. I’m editorializing for the benefit of other humans.” ?”Comment your code” and “document your code” offer the same mandate.
But I find that problematic. ?And it’s not just because I’m some kind of stickler for semantics. ?I think this causes us to have weird arguments, sometimes nonsensical and sometimes unnecessary.
Code Documentation vs Code Comments
To explain myself and my reasoning, I’ll offer definitions for both terms.
- Code comments: any meta text you put in source code.
- Code documentation: creating a conceptual maintenance manual for your source code (in the dictionary sense of documentation).
Having established that, let me stave off some possible objections. ?First, you might ask, “Isn’t the entire point of code comments to help create that user manual?” ?In theory, maybe. ?But in practice, come on, you know better. ? People use comments to add legal boilerplate, express themselves with ASCII art, try their hand at comedy, and probably even to gossip.
Secondly, maybe you’re someone that concedes that people do use comments this way, but you say that it’s abuse. ?In other words, sure, that happens — but it shouldn’t. ?If people did code comments right, they would all constitute code documentation. ?But I would still argue against this idea. ?Code comments can represent note-taking. ?”Note to self” and “note for later” both count.
So let’s create a relationship definition. ?Code documentation means creating a maintenance manual for your code, and that manual may or may not use the code comment as a medium.
I’ll also say that I think you should document your code, but it doesn’t matter terribly if you comment it.
Code Comment Origin Story
To understand why I make this distinction, let’s take a look at the history of the code comment. ?In early programming languages, you would write language instructions and then comments, often denoted with keywords such as REM (for REMarks) or the word “comment” itself.
In early languages, these comments tended to play a more vital role in understanding than they might now. ?Disk space came at a premium, so people used terse variable names. ?Many of these languages featured jump instructions and constructs like “goto,” giving rise to the “spaghetti code” pejorative. ?In short, you’d be relatively hard pressed to understand code without explanatory comments.
Back then, programs tended to be less sprawling in terms of line of code. ?They also tended to be harder to read in and of themselves. ?So inline comments filled in the contextual blanks. ?They served as almost a part of the code.
But over the years, languages evolved and moved to higher levels of abstraction. ?Structured programming and then object-oriented programming gained mindshare, and we also had steadily more disk space. ?This allowed software developers to create more and more expressive and organized code. ?Techniques like Hungarian notation fell by the wayside.
And the occasional inline code comment went from vital to…something else. ?I’ve already offered my take on the inline comment, so I won’t do so here. ?But I think we can all agree that the ratio of comment to code characters necessary has decreased over the years.
The Evolution of Code Comments
There’s no doubt that this sort of thing has declined in our code over the years:
x++; //x is the number of orders -- increase it here at the end of the loop
We could just rename x to “orders” and extract the loop contents into a method to eliminate the need for scope reminders, not to mention that modern IDEs help us with these things anyway. ?Comments that might have proved invaluable 40 years ago just clutter our editors now.
But that doesn’t mean, over the years, that the code comment lay idle. ?Far from it. ?Instead, it has emerged as a sort of data.
As time moved forward, people got more and more formal with comments in code. ?Techniques like this emerged:
/////////////////////////////////////////////////////////////////////////////// // ALL STUDENTS COMPLETE THESE SECTIONS // Title: (program's title) // Files: (list of source files) // Semester: (course) // // Author: (your name) // Email: (your email address) // CS Login: (your login name) // Lecturer's Name: (name of your lecturer) // Lab Section: (your lab section number) // //////////////////// PAIR PROGRAMMERS COMPLETE THIS SECTION ////////////////////
You’d have some pre-canned template that should go at the top of each code file. ?This one is clearly for students, but you might also find them with the name of a company or an open source project.
From there, it was a pretty short jump to starting to treat code comments as first class data in their own right.
Intelligent Comments
I can still remember the first time I encountered intelligent comments. ?I’d been using templates like the one above for some time in C and C++ code that I wrote for Linux kernel modules. ?But then I switched over to doing some stuff in both Java and .NET, and I discovered something awesome.
Instead of formats like the one above, you could write comments like this one, in C#.
/// <summary>
/// I like re-inventing wheels, so enjoy this Add method
/// </summary>
/// <param name="x">First number to add</param>
/// <param name="y">Second number to add</param>
/// <returns>The sum of the numbers</returns>
public string Add(int x, int y)
{
return x + y;
}
As far as the compiler was concerned, this was just any old comment one might write. ?But the IDE did something a lot cooler with it. ?If you wrote this style of comment above a method, and you used that fancy looking XML formatting, IntelliSense?in the Visual Studio IDE would parse the comments and render them as meaningful data while you coded. ?This was code intelligence. ?With an instance of the parent class, call it Calculator, you could type “calculator” and then hit a period, and see that it offered the Add() method, exactly as described in the comments.
Wow.
Java offered a similar construct as well. ?And of course it did. ?This represented the future of the humble code comment. ?Treat them not as random text, but as proper data (or metadata, anyway).
The Shift to True Documentation
Why go through all of this history? ?Because I wanted to demonstrate how code comments evolved over the years. ?Originally, it represented the only reasonable means of deciphering terse and often confusing instructions. ?But as our languages grew more expressive and our collective mastery of them more ubiquitous, what we could express both with the language and with the comments around it improved.
Software and the code that defines it have exploded in diversity, complexity, and scope over the decades. ?With so many more people maintaining so much more code, we’ve had to scramble to make maintenance even remotely sane. ?And we often fail, resulting in applications being wastefully rewritten whole cloth.
But when we succeed, we do it by having a strategy for maintenance that involves true code documentation. ?This means a concerted effort to write a conceptual manual for maintainers. ?You could try to do this with code comments alone, but that’s unwieldy. ?Similarly, people have used things like Word documents, wikis and SharePoint sites over the years. ?But those get out of sync more easily, since they aren’t right inline.
The true sweet spot lies in the judicious use of comments, and of turning those comments into the data that drives proper documentation. ?So sure, you can?comment your code as an understanding stopgap. ?But don’t stop there. ?Look for ways to turn your comments and code metadata into proper documentation. ?Document your code.
Learn how GhostDoc can help to simplify your XML Comments, produce and maintain quality help documentation.
1 Comment. Leave new
[…] the SubMain blog, I wrote about how code comments and documentation aren’t the same thing.? Anything you stick in the codebase with a couple of whacks in front of it is a comment.? But […]