← Corpus / lost-in-public / reminder
Maintain Robust Commenting in our Flavor
Unlock the power of readable, maintainable code with our signature commenting style—section openers, function docs, and clarity-first annotation for every project.
- Path
- reminders/Maintain-Robust-Commenting-in-our-Flavor.md
- Authors
- Michael Staton
- Augmented with
- Windsurf Cascade on Claude 3.5 Sonnet
- Tags
- Code-Style · Documentation · Code-Comments · Readability
Coding Guidelines
- Declare types inline. Aggregate a list of the types information in the comment sections
Comment Syntax and style.
- This is a section opener.
/* section open ==============================================================
|
| ??-- About: Section Name
| ??-- Type: User Options
|
| ??-- Includes:
| //---- List
| //---- of
| //--
====================================== */- This is a section closer.
/* ========================================
??-- Affects:
//---- list of
//---- code blocks
//---- that this section affects
//
// Close: Section Name
// ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^*/- This is function opener template.
/* function: -------------------------------------------------->
??-- Purpose
//-- Lines describing desired functionality
--- continued from previous line.
-->
??-- Logic
//-- Explain how this function would be called
---- with arguments and arguments
---- 1. with steps and steps
-->
----------------------------------------*/An example:
/* export function: -------------------------------------------------->
??-- Purpose:
//-- Turn all backlink syntax into relative path hrefs
---- in the Markdown file or Markdown files passed through parameters.
-->
??-- Logic:
//-- Called form page rendering from rendered Astro components.
---- 1. Receives an array of paths to Markdown files or one Markdown file.
---- 2. Creates an empty array `backlinksFoundInMarkdownContent`.
---- 3. Adds to array when regex matches backlink syntax '[[${Page Name]]'
---- 4. Scans an index of pageName keys to match the string inside the square brackets.
---- 5. Replaces the backlink syntax with the relative path href.
-->
----------------------------------------*/- This is function closer.
/* returns: ----------------------------->
- object or value explanation
- object or value explanation to: list of places where this function is called.
- functionName, fileName.ts end function --------------------------------------------------*/