> Clarity is subjective. Function and variable names that are > clear to one person, may be obscure in the eyes of another > person. We know from other venues that a topic is better > understood if different explanations of the topic is > provided. In my experience this also applies to source code.
One obvious example here is when you are debugging code written by someone who speaks another language - the names may well be meaningful in *their* language. > One useful type of comments are summaries of what a function > does. A parallel is found in technical papers and books which > usually start each chapter with a summary of what you can > read in that chapter. I hate books that have summaries at the start of sections. It is an insidious trend that should be stamped on hard - I see theses with summaries at the start and end of chapters and then at the start and end of sections. It's extraneous padding. Awell written book should be able to be skimmed by a proficient reader without the need of summaries! > Another useful type of comments are explanations of why a > function works as it does, rather than how something works. "You are not expected to understand this" Perhaps this is the point to tell my comment story about what happened to a friend of mine. He was debugging some code and had narrowed it down to one section where there was a comment "AWB 9/10" - he puzzled at this for ages to try and get it to help him and eventually located the author of the code (who happened to still be around) and asked what it meant "Oh", he said, "There was an Average White Band concert on the ninth of October...." L. - Automatic footer for [EMAIL PROTECTED] ---------------------------------- To unsubscribe from this list, mail [EMAIL PROTECTED] unsubscribe discuss To join the announcements list, mail [EMAIL PROTECTED] subscribe announce To receive a help file, mail [EMAIL PROTECTED] help This list is archived at http://www.mail-archive.com/discuss%40ppig.org/ If you have any problems or questions, please mail [EMAIL PROTECTED]
