Roman Neuhauser wrote: > # 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'm with you on that. I love the "modularity" of the language. > 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. Sounds like someone who is very comfortable with the language. I wanted to look at some practical examples (something that was actually in use as opposed to some examples from a book) so I opened up phpmyadmin. It may as well have been written in a different language. I couldn't figure it out and there weren't many comments to help me. I hope one day I will be as comfortable in php as I am in English, but for now, I need the interpretation found in comments. > (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! ;) I'm a little embarrassed to say that when I started, that was one of the things tripping me up, until I read the reason for putting the literal on the left. >> 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. > -- Brian P. Giroux Sénécal & Associé.e.s / Associates Recherche et marketing / Research and marketing Tél : (705) 476-9667 Fax : (705) 476-1618 www.senecal.ca -- PHP General Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
