Roman Neuhauser wrote: > # jochem@xxxxxxxxxxxxx / 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
