Lindsay Marshall wrote: > > 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!
Well, replace chapter introductions with academic abstracts or business executive summaries in my comment above. The point is that reading a concise and descriptive introduction (or a function comment) before reading the detailed description (or the function itself) can save time by helping to determine what is relevant to the current task. If you dislike such summaries, feel free to skip them. - 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]
