On Sun, Jun 04, 2006 at 01:57:40PM -0700, Andrew Lentvorski wrote: > Lan Barnes wrote: > >At the least, programmers notes with a discussion of overall > >architecture, which files hold which functionality, a HOWTO on adding > >procedures. > > The only one of those I agree with is the discussion of overall > architecture. > > >And the code still needs good comments within. > > Comments *lie*. Code tells the truth. >
Only when developers are too lazy/incompetent to keep them updated. Note that a comment history (i.e., leaving the previous comment in and dating and signing the change comment) can be very helpful to the diagnostician. And on the subject of SCM, first, all decent SCM tools allow for a revision comment, so that's an appropriate place to document, as well as in the code; and second, SCM is more (much more) than tools ... it is processes first. At our shop, there is no authorization for a developer to change a space or a comma without an assigned task directing the change or change set. We are subject to FDA audits and people die when code in devices like ours doesn't work, so there is no leeway for changing the names of variables or prettying up spacing until the dev lead/project manager has assessed the risk and written a tracker task assigning the prettification. And even then it may trigger (expensive) regression testing. There is no room for the arrogance of "my code speaks for itself" when you can (1) kill people and (2) get the company shut down. -- Lan Barnes Linux Guy, SCM Specialist Tcl/Tk Enthusiast -- [email protected] http://www.kernel-panic.org/cgi-bin/mailman/listinfo/kplug-list
