Today's entry, provided by Elizabeth Naramore, is entitled Writing Code is Like Doing the Dishes (5 Reasons Why Documenting Your Code Makes You a Better Coder).

Name

Elizabeth Naramore

Blog

naramore.net/blog/

Biography

Elizabeth is an active member of the PHP Community, the co-founder of PHPWomen.org, the organizer of OINK-PUG, and a moderator at PHPBuilder.com. She has also done freelance writing for Wrox/Wiley and International PHP Magazine, and she currently acts as the News Editor and Managing Editor, Books for php|architect. In her day job, Elizabeth works in e-commerce and does web development consulting.

Location

Cincinnati, Ohio

When I had my appendix out last year, and my husband had to go back to work, I needed help. My mother-in-law graciously offered to come stay with us and help. Gratefully I obliged, so the next day she was at our house, ready to go. The first task at hand was to clean the kitchen and put the dishes away. It's funny when you're in someone else's kitchen, and you have no idea where things go. The poor soul kept having to ask me where every cup, plate, pot, and pan went. I didn't mind, of course; how else would she know? We all have our little ways of doing things. So then we came to the little kids' plastic cups.

"They go underneath the cabinet," I said. "Down by the pots and pans."

She gave me an odd look, so I explained. "That's so the kids can reach them themselves. They go on that little shelf where the pan lids should go."

She opened the cabinet and started putting them away, and then she asked, "So where are the pan lids then?"

"Oh, those are over there on the other side of the kitchen in the other cabinet. It was the only place big enough to hold them. They're with the bread maker and the waffle iron."

This brings us to my first point.

1. You should document your code like you would tell a stranger how to put the dishes away. Anyone having to maintain your code is not going to think the same way you do, and your reasons for doing things may not be obvious. Someone once said, "If your code is written well enough, you shouldn't have to document it." This may hold some water with what your code is doing, but in my opinion, it doesn't help with the why your code is doing what it's doing. Yes, it's tedious. Yes, it can make you feel defensive at times. But, remember your successors are not mind readers. If my dishes were my code, and I simply said, "Now, I'm putting the pan lids over here with the bread maker and the waffle iron," anyone reading my code would think I'm nuts. But, if I elaborate on the reasoning behind it, then it might make more sense (especially to those who have little kids).

Let's go back to my code == dishes analogy. One thing I found interesting is that my husband loads the dishwasher completely differently than I do. We've been living together for roughly 12 years, so one would think we would have adopted the same habits. Not true, I say. He puts the plates on the left; I put them on the right. He puts the coffee mugs on the bottom; I put them on the top. He doesn't pre-wash; I do. We get the same result most times, so it's never really been a big deal to either one of us, but one day he asked me why I pre-washed the dishes.

"To get the crusty stuff off," I said.

"But doesn't that defeat the whole purpose of having a dishwasher?"

Eventually I acquiesced and agreed to try it his way. I found that sure enough, our dishwasher was hearty enough to clean off the gunk 9 times out of 10. Of course, I still fight the habit of pre-washing, but this brings me to my second point.

2. Documenting your code helps you examine each step of the process and question the answers. Sure, we always had clean dishes, but once I had to explain myself, and the answer I came up with wasn't exactly foolproof, I was willing to think outside of the box a bit and try something I'd previously been reticent to try. If you're documenting your code, you're really looking in detail at how/why things are coded, and opening up the possibility of making it better. Just because something gives you the desired result, doesn't mean it's the best way of doing things. And you might save yourself some tedious steps along the way (no more pre-washing!).

So anyway, I'm helping with the dishes at my parents' house after Thanksgiving, and I'm putting the silverware away. My parents always load the silverware pointing up, so that the dishes get cleaner. This doesn't work so well with our dishwasher, as you would not only stab yourself on the fork tines in order to put them away, you'd be grabbing the part that you're going to be sticking in your mouth later. But, the nature of my parents' dishwasher is such that the silverware holder is flat and opens from the front, allowing full access to each piece inside. So, you can safely and sanitarily grab them by the handle to put them away.

"This would never work at my house," I said. "We have completely different hardware."

3. Documenting your code keeps you mindful of portability, scalability, and performance. If you're constantly looking at each step of your code, and mapping it out through documentation, you're able to see where system-specific issues might be occurring, especially if you're taking advantage of a benefit unique to that system. For example, if you're writing PHP 5 code, but you want to make it easy for someone running PHP 4 to still be able to use it, you can use documentation to flag anything PHP 5-specific.

Once, our dishwasher broke, and we had to call the repairman. (God forbid we wash our dishes by hand, mind you.)

"Tell me exactly how you loaded this thing," he said.

"Well, I put a few plates in, then the cups and silverware, alternating between what was next in the sink. Kind of like a LIFO system." He looked at me kind of funny; I guess people usually just said "I put the dishes in, duh!"

So, I continued. "Then I load this casserole dish, and the corn cob plates, and the corn holders."

He stopped me. "Did you use the little corn holder basket?" Chagrined, I said no. "Well, that's your problem. I bet you've got a corn holder stuck in the heating coil," he said smugly.

4. If you document, you'll be saving yourself and others precious time debugging. If I would have only told the repairman, "I loaded the dishes," but not what specific dishes I'd loaded, or in what order, he'd likely still be taking that thing apart, and I'd be taking a second mortgage out on my home.

I have but one more dish analogy to illustrate my fifth and final point.

Returning the favor for my mother-in-law, I was helping her do the dishes at her house one evening.

"Make sure you do the coffee cups first," she said.

Perplexed, I asked her why. She shrugged and replied, "That's just the way I like to do them."

5. Documentation can save your ass. Sometimes there really is no logical reason for why somebody wants something done a certain way. I use the phrase "at client request" in my documentation all the time. Years from now, when someone is looking at my code, instead of trashing my name, they will see those three little words, instantly understand where I'm coming from, and really be able to feel my pain. That's also my clue to my successors that this section of code is ripe for refactoring.

In short, documentation makes you a better coder. It makes you think about what you're doing down to the last detail. It helps everybody be on the same page. It helps identify potential areas for improvement, and where bugs might be occurring. It doesn't really matter what system you use for documentation, whether it's your own way or something more widely accepted like phpDocumentor. Personally I would recommend using phpDocumentor-friendly documentation in your code. If you follow its guidelines, it can automatically generate basic documentation for your application. From the phpDocumentor site:

phpDocumentor uses an extensive templating system to change your source code comments into human readable, and hence useful, formats. This system allows the creation of easy-to-read documentation in 15 different pre-designed HTML versions, PDF format, Windows Helpfile CHM format, and Docbook XML. You can also create your own templates to match the look and feel of your project.

You can read more about phpDocumentor at phpdoc.org.