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=-2.9 required=5.0 tests=BAYES_00,MAILING_LIST_MULTI autolearn=unavailable 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!news2.google.com!proxad.net!freenix!enst.fr!melchior!cuivre.fr.eu.org!melchior.frmug.org!not-for-mail From: Stephen Leake Newsgroups: comp.lang.ada Subject: Re: Writing changelog entries Date: 07 Jan 2005 21:12:59 -0500 Organization: Cuivre, Argent, Or Message-ID: References: <87y8f96imj.fsf@deneb.enyo.de> <87wtus3do0.fsf@deneb.enyo.de> NNTP-Posting-Host: lovelace.ada-france.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: melchior.cuivre.fr.eu.org 1105150406 44272 212.85.156.195 (8 Jan 2005 02:13:26 GMT) X-Complaints-To: usenet@melchior.cuivre.fr.eu.org NNTP-Posting-Date: Sat, 8 Jan 2005 02:13:26 +0000 (UTC) To: comp.lang.ada@ada-france.org Return-Path: In-Reply-To: User-Agent: Gnus/5.09 (Gnus v5.9.0) Emacs/21.3 X-Virus-Scanned: by amavisd-new-20030616-p10 (Debian) at ada-france.org X-BeenThere: comp.lang.ada@ada-france.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Gateway to the comp.lang.ada Usenet newsgroup" List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Xref: g2news1.google.com comp.lang.ada:7558 Date: 2005-01-07T21:12:59-05:00 Brian May writes: > 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. If you document why the code is the way it is, _and_ why it is not some other way that you considered, you can terminate the perpetual changes. Such documentation belongs in the code as comments if it is short enough, or in a separate design document, with a reference in the code. > 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. Change logs are not design documents. -- -- Stephe