begin quoting David Brown as of Sun, Mar 16, 2008 at 10:34:48AM -0700: > On Sun, Mar 16, 2008 at 09:23:51AM -0700, Paul G. Allen wrote: [snip] > >With code that is maintained by a team of engineers, comments as to who > >changed what, when, and why are necessary, and in most cases, mandatory. > >Often a simple changelog at the top of the file is not enough to > >adequately explain the changes made. > > Or, get a [EMAIL PROTECTED] revision control system. Any comment, anywhere, > that > describes a change or it's purpose tells me that the revision control > system is broken. If other people don't have access to your revision > control system, get a distributed revision control system.
The one exception I would make would be code changes made for performance reasons. When you replace code that is clear, short, and slow with code that is opaque, long, and fast (as verified by the profiler), there may be a tendency to rip out the "optimized" code during cleanup. > Cluttering the code with information that doesn't matter to the reader just > makes it difficult to read. A decent system will have a "blame" or > "annotate" command, and it is very easy to figure out what change put a > piece of code in place, and read a detail of the description. I can then > also look at what it was changed from, instead of just the partial > information of what it is like now. I often find that after a couple of months, I no longer care what the code was like "before". > We've actually recently just had to add an additional requirement to a > contractor to forbid them from putting these kinds of comments in code. Heh. It's listed as a "best practices" by some folks. -- Not all best practices are a good idea; their advocates should rest. Stewart Stremler -- [email protected] http://www.kernel-panic.org/cgi-bin/mailman/listinfo/kplug-lpsg
