Skip to content
Kitbay
Skill

writing-comments

NOASSERTIONUpdated on Nov 11, 202663,887GitHub stars

A maintainer skill in the Astro repository on writing comments in its TypeScript and JavaScript source for future contributors who have only the code in front of them.

What the skill teaches

A maintainer skill in the Astro repository on writing comments in its TypeScript and JavaScript source for future contributors who have only the code in front of them. It separates file overviews, which explain lasting design reasons, item docs, which describe behaviour, parameters, returns and errors, and inline comments, which explain constraints and workarounds. Comments must describe the code as it is, never its history or a reviewer, and workarounds must link an issue or pull request. It bans narrating the next line, vague hedges, emojis and section banners, gives Astro's tag conventions for deprecations and TODOs, and ends with a four-question self-check where deletion is the default.

Capabilities

  • Write file overviews, item docs and inline comments
  • Remove comments the code already explains
  • Link workarounds to issues or pull requests
  • Self-check comments before finishing