Browse Prior Art Database

Method to Allow Commentary Changes in Program Source Files Without Causing Source Code Reprocessing and Allowing Source Code Changes in Source Files Without Causing Commentary Reprocessing.

IP.com Disclosure Number: IPCOM000245641D
Publication Date: 2016-Mar-23
Document File: 2 page(s) / 27K

Publishing Venue

The IP.com Prior Art Database

Abstract

Described is a method for allowing either program code or documentation text in the same source file to change independently without a basic assumption that code changes are the only reason text changes would be needed and vise versa.

This text was extracted from a PDF file.
This is the abbreviated version, containing approximately 51% of the total text.

Page 01 of 2

Method to Allow Commentary Changes in Program Source Files Without Causing Source Code Reprocessing and Allowing Source Code Changes in Source Files Without Causing Commentary Reprocessing .

Combining program code and its documentation into a single source file enables a tight interlock between code function and the publications that describe that function. In theory, this single point of maintenance keeps both deliverables in sync. The fundamental assumption being that program code will change over time and, as it changes, the documentation text embedded in the same source file will also be changed. Where this assumption breaks down is in the real world of publications delivery where publications can undergo review, corrections, additional notations, and feedback without any affect on program code. The publications process can drive changes into the source file and doing so triggers all library management and version controls on the program code to be engaged. Build processes for code recognize changes in the source file and trigger new code builds or fixes even if the program code did not change. What this article addresses is a method for allowing either program code or documentation text in the same source file to change independently without a basic assumption that code changes are the only reason text changes would be needed and vise versa.

    There are computer program code products that embed documentation within the commentary of the source code files. The convenience of having a single file of source for both program code and documentation avoids the paradigm of dual maintenance for both source code changes and documentation changes. This model makes it easier to keep the function of the code and the documentation in sync.

    The inherent problem with this model is that when documentation must be updated, for any reason other than changed program behavior, then once the single source file is updated, the library processing tools trigger rebuilds of the affected program code components. There was no code change, but the commentary in the source file had to be updated in order to generate a new revision or version of documentation. This is an extra burden for change management in the library system because source code compiles are re-run and new executab...