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 Path: g2news1.google.com!news3.google.com!news.glorb.com!border1.nntp.dca.giganews.com!nntp.giganews.com!local1.nntp.dca.giganews.com!nntp.megapath.net!news.megapath.net.POSTED!not-for-mail NNTP-Posting-Date: Mon, 10 Jan 2005 14:56:09 -0600 From: "Randy Brukardt" Newsgroups: comp.lang.ada References: <87y8f96imj.fsf@deneb.enyo.de> <87wtus3do0.fsf@deneb.enyo.de> Subject: Re: Writing changelog entries Date: Mon, 10 Jan 2005 14:57:46 -0600 X-Priority: 3 X-MSMail-Priority: Normal X-Newsreader: Microsoft Outlook Express 5.50.4807.1700 X-MimeOLE: Produced By Microsoft MimeOLE V5.50.4910.0300 Message-ID: NNTP-Posting-Host: 64.32.209.38 X-Trace: sv3-9jNweE0AnJgFcF+UAA8vmFDmUkjfsv75EfFgTm1gqQmPZi/2dOsfro0QPsfnylm2MUoZ9EVYJWlUwrQ!ChZfaf5T1K83avCq7aNnpzP7U1hZfc2rNPz8LJXqAsXOjLi+jpyLq8tet3gY9ibA6Y9HiN8KSOOg X-Complaints-To: abuse@megapath.net X-DMCA-Complaints-To: abuse@megapath.net X-Abuse-and-DMCA-Info: Please be sure to forward a copy of ALL headers X-Abuse-and-DMCA-Info: Otherwise we will be unable to process your complaint properly X-Postfilter: 1.3.22 Xref: g2news1.google.com comp.lang.ada:7619 Date: 2005-01-10T14:57:46-06:00 List-Id: "Brian May" wrote in message news:sa48y74n7bq.fsf@snoopy.apana.org.au... > >>>>> "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. The code should be commented as to why it is the way currently is. Of course, that isn't always done (when it appears obvious). But if a bug report causes a change, usually I'll include the bug report number and an explanation of why the code needs to be the way it is. > 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. Well, unless I've lost the ability to read comments, that's not likely to be an issue. Moreover, I would be remiss if I don't use the bug report number to look up the associated regression test to insure that I didn't reintroduce a bug. > 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. Couldn't happen: even if I didn't manually check for a regression, the regression tests (which are run very often - usually immediately after a change) would have caught the problem. For this to happen, I've have to have failed to comment the code *and* failed to create a regression test. I'd fire myself if I did that! > ...repeat... > > See a pattern here? Sure; some people neither create tests nor properly comment their code. What good would a changelog do? It's widely separated from the code in question; I don't want to have to look in a half dozen places to understand some code! And if people aren't putting in useful comments or creating tests, why would they write a useful changelog?? (Certainly, if I didn't do the first two because I was in too much of hurry, the third will be even more useless...) > 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. Absolutely. At the place of the bug, in the code where you can't help but see it the next time your debugging path leads you there. > 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. Those would be pretty useless comments. The only comments that *are* useful are those that explain *why* code is the way it is. The other questions (what, where) usually can be answered by reading the code itself. > 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. I don't see why; it's widely separated from the code in question. There is no sane way to associate the descriptions with the code -- and that's what you need to understand the code and avoid reintroducing problems. I don't believe in separate design documents (other than for "big picture" sorts of descriptions), either. > 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. We always tried to keep the systems maintained in parallel. Traditional source code control systems do a lousy job of this, and we wrote our own tools to manage the files (most of them are shared between the versions, only a few need manual upgrades). But I realize that won't work everywhere. > Not to mention security related issues. A good changelog may help > identify what versions of the software had a serious security bug for > instance. That seems like a job for a bug tracking database. We've never computerized that (I still use the paper-based system we worked out in the 80s), but it would be easy enough to do. I don't want to claim that the changelog has no use whatsoever, but I don't think there is much point to getting fancy with it. There are better places for virtually all of the information that could be in it; you just need enough to insure that you can find a particular change in the rare case that you need to see how you got to the current code. Randy.