Comments on: Point, Counterpoint

By: Francois Schiettecatte

Francois Schiettecatte — Sun, 19 Feb 2006 15:47:22 +0000

I don’t agree that you don’t need to document your code when working alone. Whatever code you write will have to be maintained at a later date, whether it is debugging because you suddenly get that one bit of data you did not expect, or because you want to add functionality. And this may happen tomorrow, or next year. In both cases I have been glad that I took the time to document my code because it makes it so much easier to understand what is going on.

By: Marcus Bointon

Marcus Bointon — Sat, 18 Feb 2006 19:04:10 +0000

‘Notes to self’ are extremely useful - in particular the phpdocumentor @todo tag as it generates noce reports on stuff you’d forgotten about. I noticed that PHPEclipse also picks out any comments that contain ‘TODO’, even outside docblocks. Even though I’m working on my main project alone, I know that it’s very likely that I’ll want someone else to work on it at some point, so inline documentation is worth prioritising for me.

By: Codechick

Codechick — Sat, 18 Feb 2006 01:33:11 +0000

I haven’t listened to the podcast yet, but that’s next on my list…

I do think that even in a one-[wo]man shop documentation can be a helpful thing. You may be the very person who needs to read your own documnetation, especially if you cycle through lots of projects on an ongoing basis.

Have you ever thrown something together, under the gun, with “no time to document,” only to return to it months or years later, and found yourself thinking “what on earth was I doing here?” or “what was I on when I wrote this?”

This is a case where some documentation, or “notes to self,” would come in handy. Especially if you are under the gun again, and don’t have time to ponder your sanity.

By: Xing Li

Xing Li — Fri, 17 Feb 2006 22:04:04 +0000

I agree with Scott when it comes doing what you need to do in a one-person shop.

I would love to document my code but the only time I did was to show it to someone else. Otherwise, I’m the code master, judge, and executor.

Source control is good even for a one man shop but not really for the reasons of tracking changes and more in cases of diaster recover in my case.

It really comes down time, resouces, and most importantly, motivation.

If you are the only one in-charge and writing the code, who is going to read your documentation? No one and no one is notorious for killing motivation for anything in everyone.

If and when I join a team environemnt, you can bet your house that I will have the best doc on the planet to show case my code quality. That’s motivation.

For now, stuff like documentation is out the window and I’m already stepping on the gass so the documentation police can’t catch up. =)