Commenting functionality

[OliverTod]

Allow commenting for the dual purposes of:

• debugging; and
• notes to other template developers

Use Case 1: Notes to other developers

Comments would be programmer-readable explanation or annotation in the cicero template. These comments will be added with the purpose of making the source code easier for humans to understand. The text in the comments are not included in the final rendering(s) of the grammar file.

For this use case, comments will likely only contain plain text - there will not be TemplateMark syntax inside the comments - and only be used in individual lines / code blocks.

Use case 2: Commenting out code

Comments can also be used to comment out a code snippet, meaning to add comment syntax causing that block of code to become a comment, so that it will not be executed by the compiler. This may be done to exclude certain pieces of code from the final template, or (more commonly) it can be used to find the source of an error. By systematically commenting out and running parts of the program, the source of an error can be determined, allowing it to be corrected.

For this use case, comments will likely contain TemplateMark syntax and apply to several lines / code blocks.

Issues

Some issues to discuss / look out for:

• what syntax would comments in TemplateMark use?
• how will commenting functionality be put into the VS Code extension so that existing keyboard shortcuts work?
• will comments be removed when a contract instance is created? Will comments be supported in contract instances?

[OliverTod]

I thought you would all get a kick out of this part of the wikipedia entry on 'Comment (computer programming):