PHP functionphobs and doccomment fans

So in PHP functions are basically used in two cases: If the programmer doesn’t yet use OOP or if the script isn’t worth using OOP for. The notion of “helper function” or something like that does not seem to exist…(Reminder: Using classes does not mean your code is object-oriented!)

So true! But what really got me on this article, was this part:

Another tangentially related “standard” practice I feel badly about is the excessive use of doccomments. In most cases phpdoc comments just comment the obvious – at the same increasing the code size by a factor of two or three. I have no problem with doccomments where necessary, but in most cases (at least with well designed code) the behavior should be obvious from the method and parameter names.

Coming from a Perl camp and being a fan of Ruby for few years (still using them here and there), I start catching myself thinking that the world’s been taken over by crazyCamelCaseJavaProgrammers. I do understand that complex projects with huge (no, “huuuuuuuuge!” would be more appropriate here) codebase need concrete descriptive variables, but what happened with readable code? The less readable it becomes the more comments it generates. Sometimes the only expression you get after reading a doc file on the class is “Thanks, Captain Obvious!”. Commenting return statement with “return” comment, or “note: division by zero” and here it comes – division by zero.

I guess that I’m too picky on this one, but by the end of the day remember what this oldie:

Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live. Code for readability.

Leave a Reply