I’m guilty of not always documenting my code. Last week I finished up a big project, lots of new code, and by the end I wasn’t documenting the code because I thought, “the code is obvious, just read it.” And while the code may be obvious if one reads it, I realized yesterday that one probably doesn’t want to read it at first. I realized this when I found myself reading code docu/comments Baron put in some new modules for mk-index-usage. He wrote a bunch of code while I was working on my project so when it was my turn to work on mk-index-usage and I needed to bring myself up-to-speed I read Baron’s code docu, not his code. I trust that if Baron’s comment says “do x and y” then the code following does x and y and, until I need to tinker with x and y, I don’t care how x and y are actually done. My code doesn’t afford Baron that luxury because not everything is documented. So poor Baron had to actually read my code. Perhaps the real irony and question is: why would I take time to blog about this but not take time to write code documentation?

Tags: comments, documentation, irony