-*- Mode:Text; Package:GLOBAL; Base:10 -*- A Proposal for Flagging Source File Changes Revised Draft 22Sep88 - smh - - - Background: Whenever one of the several Falcon implementors makes a change to any source code, there is always a chance that the change wil be incorrect, or at least will impact some other part of the system in an unanticipated way. It is important to be readily able to identify changes to source files, not only as to their existence, but as to their creators and creation dates. M-X Source Compare, the existing a posteriori mechanism for determining changes among pairs of files has behaved unreliably and cannot analyze more than two files at a time. A more general purpose mechanism for entering changes into source files is required The Proposal. 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 . . . 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 proposal is intended to apply to *all* Falcon source files, i.e., all files which are pointed to by the master K-SYS: K; SYSTEM.LISP file. This even includes those lambda files which the cross compiler shares with the native Lambda compiler. We might or might not extend it someday to Mac support files, but they are not presently at issue. It should be further understood that edit history comments in code are intended to be temporary. Anyone is free to flush uninteresting ones after four to six months have elapsed. Discretion is needed. Obviously, the history of some changes becomes uninteresting relatively quickly (but *never* so soon as a month or two!!) while comments about the motivation for other changes may become an important part of the design record, and may be worthy of permanent retention. Comments: Jim: I like the intent of this proposal but am concerned about the long term effect of having comments like ;;; ||| I moved this macro to the head of the file litter the code for years to come. I also agree that it is dangerous to try to have a tool automatically edit code. Instead I simply suggest that we agree that after an appropriate period of time (I suggest 6 months) that the comments can be edited to reflect the true state of the exiting code and comments in place simply to note that a change has taken place can be removed. Smh: I agree with this, and have edited the proposal accordingly. Oct 3, 1988 Jim: I would like to propose that this proposal be modified to discuss the coding conventions discussed below. Subject: Coding conventions I was just going through my old mail and saw this. What do people think about merging this into smh's prop-04? Accordingly when the code has been corrected to be a macro (for @@@) or handles boundary cases correctly (for +++) that a ||| comment be left behind for later deletion as per normal practice for ||| comments Status: Accepted 23sep88