Roman Neuhauser wrote:
> # [EMAIL PROTECTED] / 2007-01-12 01:57:27 +0100:
>> Brian P. Giroux wrote:
>>> If anyone can help me out with that or provide any other advice about
>>> the rest of it, I'd be grateful.
>>> The file can be found at http://www.senecal.ca/normnums.php.txt
>
>> keep commenting all your code to that extent! you do us proud :-)
>
> I find the *inline* comments superfluous and cluttering the code. They
> don't add any insight, they simply repeat what the code already says very
> succintly:
it is anything but superfluous imho - the comment describes what the line of
code *should* be doing - given that the code itself maybe changed (and
possibly broken) the comment serves as a mechanism to check that
the specific line of code *actually* does what was intended - with the comment
there is no way to know for sure that the logic of the code (even though
it may be syntactically correct) does what the original developer *intended*
I have found myself fixing logic bugs in code that I *thought* did what it
intended but in reality did something slightly different - related comments
help to remind me/you/us/them what the intention was regardless of what was/is
actually implemented.
>
> 1 function is_valid_isbn10_check_digit($cd) {
> 2 // check if th function was passed only a single character
> 3 if(1==strlen($cd)) {
> 4 // check if the digit is a valid ISBN-10 check digit
> 5 if(is_numeric($cd) || 'x'==$cd || 'X'==$cd) {
> 6 return true;
> 7 } else { // the digit is invalid
> 8 return false;
> 9 }
> 10 } else { // the check digit isn't 1 character
> 11 return false;
> 12 }
> 13 }
>
> Comments on lines #2, #4, #7, #10 only restate painfully obvious things.
> Who needs to explain that "13 == strlen($ean)" checks that the length of
> $ean is 13?
consider it not some much an explanation but a statement of intent (see above).
secondly I, personally, find it useful to write a stub function with comments
in that describe the various logic steps the function will be doing and then
later
actually write the code that accomplishes it.
at the end of the day the ammount of comments written/used is somewhat
down to personal preference/requirements. that said comments can't really hurt
so long as the content of the comments are accurate!
>
> This shorter version is more readable for me:
>
> 1 function is_valid_isbn10_check_digit($cd)
> 2 {
> 3 return (1 == strlen($cd)
> 4 && (is_numeric($cd) || 'x'==$cd || 'X'==$cd)
> 5 );
> 6 }
>
> The code is quite complicated for no good reason I could see:
>
> 1 function is_valid_ean($ean) {
> 2 //check that the string is 13 characters long
> 3 if(13==strlen($ean)) {
> 4 // make sure all digits are numeric
> 5 if(is_numeric($ean)) {
> 6 if(0==digit_sum($ean,1,1,3)%10) {
> 7 return true;
> 8 } else { return false; }
> 9 } else { return false; }
> 10 } else { return false; }
> 11 }
>
...
>
> Third step:
>
> 1 function is_valid_ean($ean) {
> 2 return (13 == strlen($ean)
> 3 && is_numeric($ean)
> 4 && (0 == (digit_sum($ean,1,1,3) % 10))
> 5 );
> 6 }
>
> The last version tells me what I need to know, and tells it only once!
> The three lines are so little of so "uninteresting" code, (there's
> obviously nothing overly complicated going on) that they don't need more
> explanation than a good function name provides.
I dispute the value you give the comments - obviously the ability of the
programmer(s) writing/using the code determines to some extent the level of
comments that are useful - from what I gather your (Roman) own skills are
quite advanced and as such you probably *require* less in terms of
comment feedback in code you use/write.
I do agree with you premise (& example) that the code can be made alot
more compact and thereby (imho) also more managable/readable.
>
--
PHP General Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php
