Re: Coding Standards Question

From: Date: Wed, 04 Oct 2006 01:23:49 +0000
Subject: Re: Coding Standards Question
References: 1  Groups: php.pear.qa 
Request: Send a blank email to pear-qa+get-3954@lists.php.net to get a copy of this message
On 10/3/06, Greg Sherwood <gsherwood@squiz.net> wrote:
Hi everyone, I've had a bug submitted for PHP_CodeSniffer (a package that checks code for violations of the PEAR coding standards) about comments inside function calls. I'm not sure what the convention is here so I'm not sure if I should throw an error, a warning, or nothing. This is an example: $wrapped = wordwrap($line, 27, "\n", true /*wrap long words*/); And this would be the (very) extreme example: $wrapped = wordwrap($line /*line to wrap*/, 27 /*length to wrap*/, "\n", true /*wrap long words*/); The coding standard doc on function calls doesn't mention comments inside the call itself. http://pear.php.net/manual/en/standards.funcalls.php So my question is, should comments inside function calls be first stripped out and then the resulting form of the function call checked? or should comments inside function calls be disallowed in favor of either a docblock comment for the "wordwrap" function, or a comment above the function call itself?
Well...there isn't any standard on this but in general comments should be avoided in-line. If you have to make a comment within a line of code you probably need to refactor. I personally only use such a thing when testing and commenting out specific things. I would say the following should be our (unofficial) standard. 1) Always try to have comments on a different line than code 2) If needed a comment may be appended to a line of code with // wordwrap($line, 27, "\n", true); //wrap long words 3) If more is needed for a very complex function call (Note: complex function calls should be avoided in favor of refactoring of some kind), each comment should be appended to a different line with // $wrapped = wordwrap($line, //line to wrap 27, //length to wrap "\n", true //wrap long words ); (Note: spacing above is just for conveience in e-mail, actual CS may differ.) I don't think that we should make this part of CS, however, as this is getting really nit-picky. At most I would throw a warning on such things, possibly only if the checker is being pedantic. (sniff --pedantic). -- Justin Patrin

« previous php.pear.qa (#3954) next »