Nicholas Nethercote <[EMAIL PROTECTED]> writes: > On Sun, 2 Dec 2007, Andreas Schwab wrote: > >>> | 2007-11-30 Jan Hubicka <[EMAIL PROTECTED]> >>> | >>> | * ggc-common.c (dump_ggc_loc_statistics): Reset ggc_force_collect >>> | flag. >>> >>> How could a newcomer guess why the gcc_force_collect flag needs to be >>> reset? >> >> That is supposed to be written in a comment. > > Indeed. Some advice I once wrote: Often I see a commit with a log > message that lovingly explains a small change made to fix a subtle > problem, but adds no comments to the code. Don't do this! Put that > careful description in a comment, where people can actually see it. > (Commit logs are basically invisible; even if they are auto-emailed to all > developers, they are soon forgotten, and they don't benefit people not on > the email list.)
Moreover, if you later look at a commit log you don't know whether it still describes the current code, you have to carefully inspect the later history whether there were any further refinements, for example. A comment will be updated over time and is always (supposed to be) on par with the code. Andreas. -- Andreas Schwab, SuSE Labs, [EMAIL PROTECTED] SuSE Linux Products GmbH, Maxfeldstraße 5, 90409 Nürnberg, Germany PGP key fingerprint = 58CA 54C7 6D53 942B 1756 01D3 44D5 214B 8276 4ED5 "And now for something completely different."