About the Author

Chris Shiflett

Hi, I’m Chris: web craftsman, community leader, husband, father, and partner at Fictive Kin.

PHP Advent Calendar Day 2

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).

Elizabeth Naramore

Elizabeth Naramore
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.
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.

  1. 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."

  1. 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.

  1. 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."

  1. 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.

About this post

PHP Advent Calendar Day 2 was posted on Sun, 02 Dec 2007. If you liked it, follow me on Twitter or share:


1.Edward Yang said:

Don't forget about Doxygen!

Sun, 02 Dec 2007 at 21:25:23 GMT Link

2.Anonymous Coward said:

Didn't she also start that Coding Contest?

Mon, 03 Dec 2007 at 09:50:07 GMT Link

3.Jamie L said:

So basically, "Document Your Code" ... Nice tip or trick. Thanks.

Here is todays tip : function foo() { foo(); } foo();

Mon, 03 Dec 2007 at 13:54:14 GMT Link

4.Sean Coates said:


Please excuse any typographical errors I might make during this post, as I'm laughing almost too hard to contain myself at your obviously funny joke, and you seem to be the type of person who would pounce due to a typo.

With that out of the way, what are you trying to accomplish here? I found Elizabeth's anecdotes an interesting read and a nice reminder that even though people like you, Jamie, are probably intellectually superior to anyone who might come after you, the harsh reality is that those people will not always have someone of such genius to look up to to solve their woeful problems.

Chris, Elizabeth and I (along with the other 22 authors) are providing this content for free. We all lead extremely busy lives, and we normally get paid for writing, so we're doing this to help the community and because we think it's interesting.

If you're already enlightened to everything that can possible be shred with you by people who are so obviously below you, then by all means, bid farewell to your mother, go back downstairs, and visit OTHER sites, ignoring us, but at the very least stop the whining; it just makes you sound like much more of an idiot than you could possibly be.


(for the record, this post is my personal opinion blah blah blah)

Mon, 03 Dec 2007 at 15:11:48 GMT Link

5.Lorna Mitchell said:

Liz, this is a fab article and what a memorable illustration story to use to make your point :)

Mon, 03 Dec 2007 at 15:17:43 GMT Link

6.Vincent said:

Awesome story, there's PHP in everything :)

Also, the dishwasher analogies made see some more puposes of proper documenting, so it surely is useful.

Mon, 03 Dec 2007 at 15:24:03 GMT Link

7.Cal Evans said:

Great Liz!


Mon, 03 Dec 2007 at 15:28:35 GMT Link

8.Lode Claassen said:

Nice article with a great analogy :)

I'm interested because we've just got a teacher who works at a company which screens code for other companies. He said his commit would get rejected when any comments are found in the code. He is more of the readable code. And documentation of course, but outside the code.

As I always learned to put comments in my code :) I'm wondering, are there any reasons to put comments in the code against having an external-only documentation?

Tue, 04 Dec 2007 at 23:16:00 GMT Link

9.Michael Mathews said:

Lode, As the creator of a comment-based, inline documentation system myself, I've already given your question a lot of thought, so here's my take: keeping as much of your documentation as close to the code it documents as possible (ideally in or right next to the code) has two benefits: 1) it makes finding the documentation easier when you are trying to decipher some code and; 2) it makes it less likely that your documentation will get out of syc with the code, because it's easy to add/update documentation at the same time you add/update code.

This is not to say it isn't possible to accomplish those same goals with an external documentation system, it's just likely to be easier when things are all together in one place. However, it may be more important to have a system that is easy for everyone to apply correctly and consistently, regardless of what that actual system is.

Having said all that about inline documentation, you will probably still want a tool that can automatically pull those comments out and reformat them into a nice self-contained HTML index you can distribute -- then you have the best of both worlds.

Thu, 06 Dec 2007 at 10:05:15 GMT Link

10.Terry Chay said:

Another reason to document your code inside the code instead of externally is you get version control (and the whole related toolchain) for free. Especially if the comments are in Javadoc.

The anecdotes were very amusing. In keeping with the holiday season I'll recount a story I read once (can’t find the reference but here is where I copy and pasted it:

<blockquote>A child was watching her mother prepare a rolled rump roast before putting it in the oven. When the mother cut off both edges of the roast and threw them away, the child asked why she was throwing away good meat. The mother replied: "My mother taught me how to cook, and that's the way she always did it. I'm sure thata there's a good reason for doing it. I'll go and ask grandma."

So the woman went and asked her mother what the reason was for cutting off the ends of a rump roast before roasting it. The mother replied: "My mother taught me how to cook, and that's the way she always did it. I'm sure that there's a good reason for doing it that way. Let's go and ask grandma."

So the women went to ask their 80-year old progenitor why she cut off the edges of the roast before cooking it. And the old woman replied:

"Oh my! You remember that I used to do that? Well, we were very poor and only had one small square roasting pan and the roasts I would buy somehow would never fit into the pan, so I had to cut the ends off to make them fit into the pan."</blockquote>

Imagine how much poorly-documented, but usable code is like that rump roast. If only Grandma had documented why the recipe called for cutting both ends off! ;-)

Tue, 11 Dec 2007 at 22:10:53 GMT Link

11.Sean Coates said:

Terry: even worse if the originator of that method was a generation (or 2) older and had passed away. I can't even count the number of times I've inherited old code that makes no sense but am afraid to touch the particularly goopy parts for fear of breaking something.

Reminds me of the story of the Magic Switch.


Thu, 13 Dec 2007 at 20:41:04 GMT Link

Hello! What’s your name?

Want to comment? Please connect with Twitter to join the discussion.