# jochem@xxxxxxxxxxxxx / 2007-01-12 13:39:59 +0100: > 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) That's exactly one of the things that make comments dangerous: they can easily diverge from the code! Use lots of small functions, well named, with well defined tasks. It's easy to see where the code lies about itself then. Use automated tests. You won't need to check whether the code actually does what a comment says: the test either succeeded or failed. I know it sounds crazy, but (most) comments are evil. Comments are are excuses for better code, they're often no more than a vague repetition of what the code says. If the code doesn't describe what it's doing while it's doing it, then the code should be fixed. (Re "should": that word actually appears in the documentation comments, reducing their utility. "Should" is a human pronounciation of a nonexistent operator with undefined semantics, so I had to look at the code anyway.) > 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* Comments are a poor tool to find out or enforce anything about code. Who put the bugs in? Humans. What makes humans better suited to find bugs in the code than computers? > 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. Perhaps the code had some of the bad smells Fowler (w/ Beck, IIRC) describes in Refactoring. Also, automated tests would be waaay more useful: the bugs wouldn't get in the code in the first place! > > 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). See my objections above as well. Which line contains a bug? 4 // check if the digit is a valid ISBN-10 check digit 5 if(is_numeric($cd) || 'z'==$cd || 'Z'==$cd) { > 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. When I want to document a piece of code I turn it into a function. I sum up the comment I would have written into that function's name. If the code needs commenting then it's too complicated, there's not enough structure, you're using bad function/variable names, or doing something else wrong. > 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! Yes. What tool (humans introduce bugs, I want something automated) do you use to enforce that the code never deviates from the comments? > > 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 - Yes, that's obvious, but there's a bottom. I claim that comments like these do the code and programmer no good. Come on, it's just a braindead 13 == strlen($ean) Everybody who has trouble understanding that expression raise your hand please! ;) > 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. Thanks for the pat but I don't look my skills too high. For example, my skills at keeping comments in sync with the code or my skills at never misreading a comment are so poor I write (virtually) all comments in the form of code so that the computer can check everything for me. I know I cannot trust myself, too many mistakes every day remind me of that. > I do agree with you premise (& example) that the code can be made alot > more compact and thereby (imho) also more managable/readable. So you agree in the end. -- How many Vietnam vets does it take to screw in a light bulb? You don't know, man. You don't KNOW. Cause you weren't THERE. http://bash.org/?255991 -- PHP General Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
