Choose the correct comment syntax based on the file type and processing system to ensure documentation serves its intended purpose. For template files (like Jinja), use template-specific comments rather than HTML comments to prevent documentation from appearing in rendered output. Always include explanatory comments for files that might seem unnecessary but serve a specific purpose.
For example, in a Jinja template file:
{#
DO NOT REMOVE THIS FILE
This file is normally inherited from the version defined by our docs theme.
However, that file includes in-line styling which isn't allowed by our website's
Content Security Policy (CSP). This empty file overwrites the template inherited
from the theme.
#}
Instead of:
<!--
DO NOT REMOVE THIS FILE
...explanation...
-->
This ensures maintenance documentation remains visible to developers but doesn’t leak into generated artifacts seen by end users.
Enter the URL of a public GitHub repository