There’s no substitute for good judgement

Another great, flameworthy topic at Girl Developer: Documentation: A Sure Sign of Garbage Code. The title is a bit misleading though, as the problem is not documentation but comments. If you’ve got non-xDoc comments all over your code, you’ve got issues.

To save myself some typing, here’s my take on the issue, quoted (sans intro and outro) from the comments:

in my opinion, documentation is good. Comments on the other hand, may be good *or* bad. Comments can quickly become something that’s definitely not documentation.

When the WHY of something is not obvious, it should be explained in a comment.

When the HOW of something is unclear, the code should preferably be clarified. IF that’s not possible, or there is no time or some other constraint prevents it, it should be explained in a comment.

Public APIs should be documented with the appropriate documentation comment facility.

It should not be necessary to document the WHAT. If the class and method names are so unclear that you need to do it, you’ve got other problems. But as always, there are exceptions to this rule. 🙂

If you have the luxury of having others on your team, you could try asking them to explain what your code is doing just by looking at it. If it doesn’t match the way you know it works, you need to either clarify it or document it better. But the ground rule still is, as always, there are no absolutes. In these matters, you should strive to make an informed decision based on your own experience. Don’t let anyone (least of all me) dictate the way you do things.

Unless of course you happen to be on my team, in which case forget what I just said and do as I say, goddamnit!

Leave a Reply

Your email address will not be published. Required fields are marked *