This post originated from an RSS feed registered with PHP Buzz by Joe Grossberg. Original Post: Lack of Documentation Considered Irresponsible Feed Title: Joe Grossberg Feed URL: http://feeds.feedburner.com/joegrossbergatom/ Feed Description: My bullshit, your brain. Latest PHP Buzz Posts Latest PHP Buzz Posts by Joe Grossberg Latest Posts From Joe Grossberg

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.