21 Nov
2011
21 Nov
'11
7:11 a.m.
I've found the following to be true:
1 - If you wrote the code, even if it's undocumented, you are going to be
likely to know what it does when reviewed later on
2 - If you've modified someone else's code, you probably aren't going to
remember what it does
I've toyed with literate programming - it doesn't work so well when you are
writing code for other people, as the utility of the documentation is
limited by your ability to write technical documentation, and the odds of
the original design being correct is pretty low if you are delivering code
to users. You end up going back and re-writing the same code over and over
again, updating the documentation starts eating up a significant chunk of
time.
My rule for code documentation is to be terse, to the point, explain why
you are doing something as opposed to what you are doing, and only comment
when it's not obvious what's happening. IE Employee.SelectOne(EmpName)
doesn't need a comment, but DataSet.ReverseOrder(SortBy.Date) probably does.