From mboxrd@z Thu Jan 1 00:00:00 1970 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on polar.synack.me X-Spam-Level: X-Spam-Status: No, score=-1.9 required=5.0 tests=BAYES_00 autolearn=ham autolearn_force=no version=3.4.4 X-Google-Thread: 103376,254d058bd7de11b3 X-Google-Attributes: gid103376,public X-Google-Language: ENGLISH,ASCII-7-bit From: Brian May Newsgroups: comp.lang.ada Subject: Re: Writing changelog entries References: <87y8f96imj.fsf@deneb.enyo.de> <87wtus3do0.fsf@deneb.enyo.de> Date: Sat, 08 Jan 2005 10:32:57 +1100 Message-ID: User-Agent: Gnus/5.1007 (Gnus v5.10.7) Emacs/21.3 (gnu/linux) Cancel-Lock: sha1:m5NwBDnk5271G5b9BytGGtGOoWc= MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii NNTP-Posting-Host: snoopy.microcomaustralia.com.au X-Trace: news.melbourne.pipenetworks.com 1105140747 202.173.153.89 (8 Jan 2005 09:32:27 +1000) X-Complaints-To: abuse@pipenetworks.com X-Abuse-Info: Please forward all headers to enable your complaint to be properly processed. Path: g2news1.google.com!news3.google.com!news.glorb.com!newsfeed-east.nntpserver.com!nntpserver.com!news1.optus.net.au!optus!news.mel.connect.com.au!news-north.connect.com.au!news.alphalink.com.au!news.melbourne.pipenetworks.com!not-for-mail Xref: g2news1.google.com comp.lang.ada:7554 Date: 2005-01-08T10:32:57+11:00 List-Id: >>>>> "Randy" == Randy Brukardt writes: Randy> That leaves the rare cases where a problem shows up much Randy> later. In those cases, it's usually necessary to debug the Randy> entire thing again anyway. So, leaving comments in the Randy> place where the code is the most valuable, because it's Randy> where you're going to be looking anyway. Then you come to a line of code that is causing problems. You can't remember why the line was in its current form (probably a mistake, and you change it to what looks correct. Months later you observe a different problem. You change the same line of code back to the original value, because you can't remember why you changed it before, and it looked totally wrong before. Months later you observe the original problem again. After hours of debugging, you end up changing the same line of code back to the modified value, because you can't remember why you changed it before, and it looked totally wrong before. ...repeat... See a pattern here? Meanwhile, the real bug is not getting fixed. You should be documenting *why* changes are made so you don't have to reinvent the wheel every time you encounter the same problem again. Comments in the code only really describe what the code does (or more precisely: what it is meant to do), not why a change was made. Yes, you could document a complete history of why you made every change as comments in the source code, a changelog file would appear to be better suited for the purpose though. Also, a good changelog is required if you want to upgrade numerous systems, and want some idea of what is likely to break in the upgrade. Not to mention security related issues. A good changelog may help identify what versions of the software had a serious security bug for instance. -- Brian May