Words on software and web development


Posts Tagged ‘software development’

Commenting code: the 6-month rule

Yesterday I had a discussion about what I think is important in software engineering. My single biggest complaint in reading code (sometimes my own code) is that the author didn’t take the time to write concise, clear comments.

Use what I call the “6-month rule”: you’re writing or modifying a section of code. You’ve been immersed in it for hours or even days, and at the time you know exactly why you’re adding that code or making that change. It all seems obvious (or it should; programming on purpose is the topic for another post). But what if you didn’t look at or think about this project for six months, and in the meantime your memory was erased? Maybe it was a Vulcan mindwipe or maybe you just had millions of lines of other code to work on in the meantime, but you come back to that code and you can’t even remember if you were the one who wrote it.

So now, ask yourself how you would put concise, relevant comments in that would help you get back up to speed as quickly and accurately as possible?

There are a few do’s and don’ts that I’ve found helpful:

  • Do connect comments to the code they apply to. Big block comments have their place but often go unread, and therefore run the risk of becoming untrue. One-liners in exactly the right place can be moved along with the code.
  • Do be concise. Say what you need to say to help your six-month-ahead analog know what’s going on and do the right thing. You probably won’t be less busy in six months than you are now so don’t make your future self take more precious seconds than needed to grasp the concept.
  • Do be clear. Concise is good but not at the risk of being obtuse. Comments like “// Now do it” might satisfy a requirement to add comments but don’t really tell you anything. I once worked on a product that consisted of about a million lines of assembler, and the rule was that every line had to have a meaningful trailing comment. It could be a real challenge at times but was a good exercise in commenting.
  • Don’t be lazy. If you code properly, your code should keep working for years to come in completely unforeseen environments, and future generations of programmers will look at your code and be impressed with how well you organized things logically and did exactly what you set out to do. But most of us don’t write such flawless code, and adding a comment that says what you intended to do will help future maintainers answer the question “what was this coder thinking?”
  • Don’t get on a soapbox. Keep your comments relative to what’s in front of you and avoid indulging in rants about the likely ancestry of the person who designed this, or why you don’t like Perl or PHP or whatever. It may be cathartic but adds to the noise level and makes it less likely that others will take the trouble to maintain your comments.
  • Don’t make your comments personal. If you sign all your comments as a personal statement of opinion, future maintainers will be less likely to change the comments to reflect a better understanding of the code. They may add more comments so that it’s necessary to read an entire trail of comments to grasp what’s happening. That may work when the trail length is <= 2 but breaks down somewhere after 1. Make your comments functional and treat them as if they are snippets of logical thought revealing design decisions driving this particular code.
  • Don’t write comments that only you will understand. Others should eventually read your comments as well, so be clear (see above) and don’t make the language in your comments harder to understand than need be.

Commenting in a way that helps you and others quickly grasp the intention, implementation details and context of code is as much an art as a part of good tactical software development. Like any art, your commenting skills can only improve with practice.

Software strategies & tactics

There has been a lot of hoopla over the years regarding various software development methodologies. Personally, I’ve found that many of them distract from the real issues in software development. The only one that I’ve found appealing is Scrum, which is far more lightweight than most of the more traditional methods.

I find one thing missing from Scrum, however. Like most methodologies, it focuses on the strategic aspects of software development: what are we going to do, what are the steps we can break it into, how can we track our progress through those steps. It does not deal with tactics: how should code be organized, how should code be written, how should code be reviewed (if at all).

Advocates of various methodologies and certification models such as CMM (Capabilities Maturity Model) are probably jumping up and down and screaming, “But our approach WORKS!!!”

And I agree with them. All of the methodologies that have survived do so because they work. However, I’m more concerned with WHY they work than WHETHER they work at all.

Good software development aims at a balance between creative drive and consideration of consequences. There are many bright young engineers who can write code that works and find creative and well thought-out solutions to difficult problems. However, in my experience there is a widespread lack of considering the consequences of code changes or rewrites. Finding a better balance, where “better” means that the quality of code produced is superior, more maintainable, less bug-ridden, and better fits the requirements, involves a different approach.

This is what I like to call “delta-driven coding.” Anyone who spends a good deal of their time managing large chunks of other people’s code through merges will relate to this idea. Creating new code is also introducing a delta, or change.

And this is where we get back to tactics. Most methodologies are successful for a number of reasons, but one prominent (and slightly embarrassing) reason is this: they produce better code simply because they slow things down. In other words, most methodologies produce better software for the same reason that reduced speed limits are claimed to save lives: when people drive slower, they think more about where they are going and have time to react intelligently (if sober).

If we recognize the importance of delta or change, we can focus on the aspects of lightweight methodologies that encourage us to consider the impact of every change. This is the key to effective delta-driven software development.