Jasper is having a good time! He has just learned about collections, collections of records, and collections of collections, and he is enjoying himself tremendously using these complex data structures. He is deep into his program, fully conceptualizing the structures—what they mean, how they relate. And while he is in "the zone," he writes code like this without giving it a second thought:

When she looks at the code, she gets really angry. What does it mean? How is she supposed to have any idea how to fix the program when she can't even figure out what is going on? Well, there is nothing to do but push through her frustration. But she sends off a somewhat nasty note to Jasper telling him, "You should put in some comments if you are going to write such cryptic stuff, Jasper!"

Jasper comes back to work and is surprised by the email. He remembers with joy the clarity of the moment when he wrote that code. What was hard to understand? To his utter dismay, however, when he opens up the file and looks at the code himself, he realized that even he can't understand the intent of that line of code....how embarrassing!

Solution: Sometimes you really do need to add comments.

Well, Jasper knows he has lots to learn, and he has clearly made a mistake here. A comment is needed. And so he changes the code to this:

Unfortunately, when he shows this to Lizbeth, she gets even more irritated. "Jasper, this doesn't help. It doesn't tell me anything beyond what the code already says!" Jasper sighs, "So I should explain what my code is doing, right? OK, how about this."

Lizbeth exclaims:

Much better! That would have helped me tremendously last week, but it's never too late to improve one's code. Of course, there are still some problems. For one thing you've got that hardcoded "N" sitting there. Also, frankly, while it’s nice to provide the comment, it would be even nicerto write your code so that it truly is self-documenting.

"For example," continues Lizbeth, taking control of Jasper's keyboard, "rather than expose all that very low-level structural code, why not create a function whose name describes the activity and whose body contains the complicated logic? Like this...."

Jasper is very pleased with himself. Not only has he written some really cool code, but now it’s even possible to understand that code!

Wait a minute, though! Does this mean that, in fact, you don't really ever need to put comments in your code? Well, certainly, if you can write code that speaks for itself without additional comments, that is ideal. There are, however, some scenarios in which comments really are required; these include:

2 comment(s) so far...