-*- Mode:Text; Package:GLOBAL; Base:10 -*- A Proposal for Annotating Source File Changes Revised Draft 22Sep88 - smh BACKGROUND: Whenever one of the several Falcon implementors makes a change to any source code, there are several dimensions along which this change might require later scrutiny. For example, a change might represent an incomplete implementation requiring future augmentation. Alternatively, it could be a "stub" requiring a future substitution by other code. In many cases, changes have far-reaching performance implications. In general, the potential for subtle and not-so-subtle ramifications when entering changes to source files obviates the need for rigorous adherence to a standard source code comment-inclusion procedure. DEFINITIONS: For the purposes of this Proposal, a "source file" is any file that is pointed to by the relevant system defining file. For Falcons this is the file "K-SYS: K; SYSTEM.LISP". In addition, "source file" refers to any Lambda files which the cross compiler shares with the native Lambda compiler. A future Proposal may suggest an extension of this definition to Macintosh-supported files as well. MECHANISM: A. ANNOTATING SOURCE CHANGES When modifying a Falcon source file, a developer demarcates the changed section with a comment string containing all of the following components: [;]_LISP-code_Comment-type-symbol_comment-text_ [;] This indicates one or more semi-colon. As a review, here is a summary of standard practice for semi-colon usage in entering comments is as follows: Long Comments: A Long Comment is a comment which takes up the entire horizontal space (possibly excluding line-initial whitespace) of one or more contiguous lines in a LISP file. There are two kinds of Long Comment: Left Justified Long Comments (";;;"): Long Comments, all of whose lines begin in the left-most (0th) column of the file, are demarcated by three semi-colons. Code Justified Long Comments (";;"): Long Comments, all of whose lines begin in the same column as the opening parenthesis of the referent code, are demarcated with two semi-colons. In-line Comments (";"): An In-line Comment is one that does not occupy the entire horizontal line on which it is found; rather, it shares a line with (and may be found to the right of) the code to which it pertains. _ ("Underbars") Underbars in the above template indicate one or more spaces separating two fields. LISP-code In-line comments (see below for definition of comment types) which hide pieces of LISP code from the reader, evaluator, compiler, etc. should be left between the semi-colon and the Comment Type Symbol. comment-text This is the text of the comment, and should be present for all types of comment (as described below). Comment-type-symbol The [Comment-type-symbol] field uniquely identifies the kind of comment that has been entered. Currently, there are three kinds of CTS (Comment Type Symbol), representing three kinds of comments: 1. ||| This CTS is a comment for inserted code that is not likely to be changed in the future. 2. @@@ This CTS is for suggestions for improving/ optimizing existing source code. 3. +++ This CTS is for comments indicating that existing code at this particular place in the file is incorrect in some way. ** 4. &&& This CTS is used to indicate a change made systematically to many files, and is not used in the normal way. See the section on ANNOTATING SYSTEMATIC SOURCE CHANGES, below. The commentator should leave a unique, consistent insignia, set off by angle brackets, identifying himself as the commentator. Also in the pair of brackets should be the date in the format . The following fictitious excerpt contains examples of both kinds of Long Comments as well as an In-line Comment: ;;; ||| Inserted this variable for efficiency. ;;; @@@ Couldn't this be omitted entirely!? (defvar all-possible-alphabetic-text-symbols (list 'a 'b 'c 'd 'e 'f 'g ; 'h ||| I dislike the letter `h' 'i 'j 'k 'l 'm 'n 'o 'p 'q 'r 's 't 'u 'v 'w 'x 'y 'z 'aa 'ab 'ac 'ad ;; ||| This is sure getting tedious. 'ae 'af 'ag 'ah 'ai 'aj . . . B. ANNOTATING SYTEMATIC SOURCE CHANGES The intention of the above mechanism is that when a few, small, localized changes are made to a file, they will be individually annotated. Systemic changes, however, do not usually lend themselves to individual annotation. In cases where many files are modified in exactly the same way, the special CTS &&& is used inside a Left Justified Long Comment at the top of each affected file (after the mode line). For example, ------------------------------------------------------------------------ -*- Mode:LISP; Package:GLOBAL; Base:10 -*- | ;;; &&& This file contains the new version of KMAC:DONALD-HAD-A-FARM | ;;; &&& This file contains the new version of LAMBDA:HAD-A-LITTLE-MARY | | : | : | : | : | : | : | : | C. REMOVING COMMENTS FROM SOURCE FILES Most comments regarding changes to source code are intended to be temporary. "Uninteresting" comments may be deleted from the source files (without leaving a record of the deletion) after a suitable time period has elapsed. Naturally, this time period varies depending on the comment. For comments regarding action items (e.g., "This function call should be changed to a macro!" or "This code does not handle boundary conditions properly!"), the CTS should be modified after the appropriate steps have been taken with respect to the code. In such cases, a "|||" CTS and comment should be left in place of the CTS and comment that were replaced. A comment of "historical" interest only may become uninteresting and therefore deletable after as little as three months, while other motivational comments may remain an important part of the design record for a longer period of time, possibly forever. Obviously, discretion is required, and erring should always be on the side of comment retention