Lack of Documentation Considered Irresponsible
According to Giles Bowkett, documentation is, ideally, by and for computers:
- generated from code, not written by hand
- intended for an audience of software (e.g testing suites) and not developers
I don't think human-readable documentation should be allowed ... it's just irresponsible.
I agree, to an extent. The "what" comments can be often be replaced by clear variable, class and method names.
The problem is that the "why" comments — i.e. any comment that has the word "because" in it — would get lost.
Let's say the "address 1" field is limited to 255 characters, and a customer wants one that's 275 characters. Can you make the change? If the design decision was motivated by the desire to save space, you can. But if that's the limit set by the printing vendor, you can't.
I suppose that (instead of a comment) you could take the RSpec files and add in some it "should comply with printing vendor specifications" do ... test, which is run against the database schema, but that's still human-readable.
The software doesn't care why you have that particular constraint. But the people maintaining that code do.
To quote myself: "The code IS the comments."
Posted by: Kearns on December 14, 2007 5:18 PM | permalinkYes, but the code offers no insight into *why* you coded a particular way. Once I'm familiar with a language or library, I find myself wondering, with far more frequency, *why* people wrote stuff in a certain way, rather than *what* the code actually does.
Posted by: Joe Grossberg on December 14, 2007 5:41 PM | permalinkMaybe it's senility, but I comment for myself. I'll never forget the first time I saw some code wrote about a year previous and wondered what I was thinking when I wrote it.
The other thing is I think the implied assertion that all languages CAN be "naturally" written in a way that's self documenting in a stretch. Sed and perl come to mind.
Please keep it on-topic. Don't spam or advertise. Don't pretend to be someone else. Anonymity is OK, but less credible.
HTML tags are automatically stripped out of your comments for security reasons. If you want to put a link to something, just enter the URL. We'll figure it out.
