[PEPr] Comment on PHP::PHP_GenDocBlock

Michel Corne (http://pear.php.net/user/mcorne) has commented on the proposal for PHP::PHP_GenDocBlock. Comment: Thanks for your comments. I tried to address them all. pear-dev => "...name like PHP_DocBlock_Generator..." MC => Sounds good. It should probably read PHP_DocBlockGenerator actually without the underscore in-between since underscores are meant to reflect a hierarchy level as I understand. Thoughts? pear-dev => "...rename the run() method to generate()..." MC => Fine with me. Will do in the next release. pear-dev => "...newline between class definition and {..." MC => Ah! I (re)checked the Pear Coding Standards and I could not find any mention of this as a requirement. I am using the PHPEdit Beautifier with the Pear settings which does not insert a newline accordingly! I did notice though that Pear packages have classes with the newline between the class definition and {. PHP_Beautifier (nice tool btw) does that but it screws up my arrays (see comments below)! So I guess I could do that manually before I commit the last change in a file. How important is that anyway? (just asking) pear-dev => "...hiding errors when using file_get_contents - maybe you should have a better error handling mechanism..." MC => Maybe. This package is really meant for developpers not for end-users. It is also mainly meant to be used with the shell command. Simply returning FALSE if files cannot be read or written seems good and simple enough to me at this point. I agree this could become a future enhancement though. pear-dev => "...comment ... have strange indentation..." MC => Oops! Forgot to (re)beautify a couple of files. Will do in the next release. pear-dev => "...use Console_GetArgs or Console_GetOpts for parameter handling..." MC => Right! I realized too late these packages were available after I coded/tested my stuff. I could use one of the other in a future release, definitely. Which one is recommended? pear-dev => "...unreadable, please insert a line feed after each break..." MC => That is kinda hard statement :-) Anyway, some "case's" go in the same block/break, so inserting a linefeed after those break won't hurt. Will do in the next release. pear-dev => "...stick to the 80 chars-a-line soft limit ... move the comment above the code..." MC => I would like to challenge you this one. The Pear Coding Standards says " It is recommended to keep lines at approximately 75-85 characters long for better code readability." First, this is a recommendation, not a requirement. Second, this made a lot of sense in those days when screens were small and people had to print their code to read it more easily. Nowadays editors and screens allow easy reading of long lines. I personaly comment each line of code for easier support/maintenance. This often makes 120 characters or so lines. I would like to stick to that. pear-dev => "...Why do you have "// /" in your array definitions?..." MC => Well, let me explain. Some small arrays fit in one line. Others are larger and easier to read if there is one line per element. PHP-Beautify merges all lines in one single line which is not good for large arrays. The ArrayNested filter expands all arrays over several lines including small ones which is not good either. The PHPEdit beautifier always merges the first element with the array() statement which is not always wanted. Adding /// does the trick and fools the beautifier; that is all I found! I guess it does not really hurt in the code. Any suggestion to fix this is welcome, really. pear-dev => "...Rethink if you need all variables private, or may make some of them protected to allow subclassing..." MC => Why not. I tend to make private those variables/methods that I do not need as public or protected as general rule. Anyway, I could look at changing some to protected in a future release based on actual users needs. pear-dev => "...add the cmdline switch to add the vim indentation settings..." MC => Good point. Could do in the next release. What should I add at the bottom of the line? I also saw "/* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */" at the begining of some files. Is this different? pear-dev => "...wouldn't ... use ... "and" and "or" to chain function calls together..." MC => I guess we all have different styles to write code. I actually believe that the use of "and" and "or" may make the code lighter and easier to read. pear-dev => "...can't specify a docblock template..." MC => Good point. I also thought of a similar enhancement, e.g. using the page-level docblock of the main class. Others may have other ideas? Proposal information: http://pear.php.net/pepr/pepr-proposal-show.php?id=481 -- Sent by PEPr, the automatic proposal system at http://pear.php.net