Better Comments

This is a reblog of a post by my friend, Steve Jones. I’ve often said that commenting code is a form of documentation, and needs to be done more.

Voice of the DBA

I assume most of your comment your code.

Well, you probably comment code most of the time.

I’d bet your comments have quite a bit of detail.

And you do this completely inconsistently.

That’s what I’d think, or maybe just what I want. Even the best developers I know will not consistently comment code. You can drift through any project on Github and see this. Those projects on GitHub might even be better documented because people know they are public. In most corporate environments I have worked in, I’ll find that when people get busy, or distracted, or even when they’re experimenting to find a solution, and they don’t write detailed comments. Usually only when someone fixes a bug, with a solution found quickly, do I get a really useful comment.

There are all sorts of ways that people think about commenting their code. I ran across a post from…

View original post 254 more words

Advertisements

Document maintenance is critical

I had two appointments this past week.  The first was one for my car to get my oil change and to make sure everything was in good working order (it was).  A couple of days later, I had a dentist appointment.  It was a routine cleaning (I also had a procedure done — one that I’d been putting off for a while).  While the two appointments were for different reasons, they both served the same purpose: to perform maintenance.

Just about everything, especially anything mechanical, is going to break down over time.  Maintenance ensures that things remain in good working order.  But when we think about maintenance, we usually think about car repair, roadwork, furnaces, and water heaters.

I’m sure many people in tech industries consider periodic hardware and software maintenance.  Hardware can break down.  Drives crash occasionally.  CPUs are upgraded to keep pace with emerging technology and to support software.  Speaking of software, bug fixes are constantly made.  There’s also the matter of security; virus software definitions are constantly updated, and operating system patches are distributed to ensure computers are safe.

But here’s another question: when was the last time you maintained your documentation?  Does your documentation, which was written for, say, Version 1.0, reflect what is in Version 2.0?

The trouble with documentation, even the best-written documentation, is that it can become obsolete over time.  Processes and systems change.  Interfaces are redesigned.  Steps become more efficient, or in some cases, even eliminated.  Change happens.  It’s one of the sure things in life.  Documentation should also change as well.  How often has your help desk received calls from frustrated customers saying things like, “your instructions say ‘press the red button,’ but there’s no red button on the interface!”

If your product changes — and it inevitably will — your instructions should change with it.  It’s important that systems are maintained.  Your documentation should be maintained as well.