Browse Prior Art Database

Ghost comments: Clarifying the meaning of obscurely named modules, libraries and functions. Disclosure Number: IPCOM000239040D
Publication Date: 2014-Oct-03
Document File: 3 page(s) / 30K

Publishing Venue

The Prior Art Database


Presented is a method termed “ghost comments”, whereby comments are inserted into code based on look-up of the referenced imports or functions being called. These comments are read only, in a different visual style to other comments, and can be toggled on or off to reduce code clutter. The comments can be identical to the documentation of the functions themselves, or can be overridden using a separate tagged description such as “@ghost” in the function documentation.

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

Page 01 of 3

Ghost comments: Clarifying the meaning of obscurely named modules, libraries and functions.

A common problem in software development, both in product and test development, is that modules, libraries and functions can have obscure names. One such scenario is a department having code to represent test cases (e.g. ABC123DE). Such code does not intuitively reflect what the module or function does, forcing the user to constantly have to hunt in the code or documentation to remind themselves.

    Current solutions to this problem include:
• Comments wherever these bits of code are used. This though adds clutter to the code base (and size) and depending on where the code is viewed, it can be inconsistent or missing.

• Integrated Development Environments (IDEs) allow the user to hover over said pieces of code where a pop-up box containing the documentation appears to remind the developer. This solution is excessive when all that is needed is a few quick words to jog the user's memory.

    Presented here is a method termed "ghost comments", whereby comments are automatically inserted into code, based on look-up within the referenced import or function.

    Similar (or same) information that would appear on mouse over pop-ups (but limited to a single line) would appear as a ghost comment in the IDE, represented using a different colour to a concrete comment and also being view only (not editable). These comments would be taken from current Doc-in-code style comments that are found in certain parts of the code base, with a particular format. Since it is an IDE feature, the comment symbol is only suggested for use for the benefit of the human. If multi-line comments are required, it could be wrapped, similar to how known IDEs currently wrap many import statements already.

    Advantages to alternative solutions:
• Feature may be toggled
• Configurable to limit to certain functions the developer chooses.

• Does not clutter the code base.

• No waiting for pop-ups.

• Can be used in editors such as VI where pop-ups do not exist.

• Can view multiple comments on screen to tell at a glance what the code is doing.

• Consistent and consolidated documentation.

    The following 3 code items describe the operation of the feature based upon development of a C/C++ routine that uses documented routines contained in external header files.

    We have a function declaration in SomeModule.h, displayed within Code Item

=====Code Item 1====
* This comment is from SomeModule.h!!
int someFunction(i...