skills.rest
riez
riezCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

conventions-comments

Standardize code comments and intent markers across codebases.

1|Updated Jan 5, 2023
Search Tags:#documentation#commenting#conventions#coding-standards#software-engineering#code-comments#intent-markers
One-click install
npx skills add https://github.com/riez/dots --skill conventions-comments
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: conventions-comments
Source: https://github.com/riez/dots/tree/main/.config/agentic/skills/conventions-comments
Command: npx skills add https://github.com/riez/dots --skill conventions-comments

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill standardizes the way developers annotate code with comments and intent markers, reducing ambiguity and onboarding time.

Core Features & Use Cases

  • Enforces consistent comment conventions and explicit markers (e.g., :PERF:, :SCHEMA:).
  • Improves code readability, review efficiency, and intent preservation across teams.
  • Use Case: When adding new features, insert standard markers to communicate intent and potential side effects.

Quick Start

Tag code comments with standard intent markers to clarify purpose and behavior.

Frequently Asked Questions about conventions-comments

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I standardize code comments across different programming languages?▼

Code comments are standardized by applying explicit intent markers and conventions across any language. This approach clarifies purpose and behavior, reducing onboarding time and ensuring maintainability without relying on language-specific documentation tools.

What are intent markers in code comments and when should I use them?▼

Intent markers are explicit tags inserted into code comments to communicate purpose and potential side effects, such as :PERF: for performance. Use them when adding new features to preserve intent and improve review efficiency across teams.

How do we enforce consistent commenting conventions for our engineering team?▼

Enforce consistent commenting conventions by standardizing in-code annotations with explicit markers. This improves code readability and review efficiency by ensuring all developers communicate intent and document side effects uniformly across the codebase.

Does this commenting convention approach work with any codebase and tech stack?▼

Yes, this approach applies to any codebase where developers rely on conventions for comments and markers, working across languages and teams. It requires no specific dependencies, making it suitable for diverse software engineering environments.

Why do inconsistent code comments increase onboarding time for new developers?▼

Inconsistent code comments increase onboarding time because ambiguous annotations obscure developer intent and potential side effects. Standardizing markers and conventions reduces this ambiguity, making code behavior clearer and reviews more efficient.

Related Skills

Explore More Software Engineering Skills→
codewithmukeshcodewithmukesh
640

convention-learner

...

Official
Advanced
zerobias-orgzerobias-org

comment-style-guide

Enforce concise code comment rules for JSDoc and TODO tracking.

Official
Advanced
aaddrickaaddrick
5.3k

lint

Lint shell scripts with shellcheck and GitHub Actions workflows with actionlint.

Community
Basic
ldk-hubldk-hub

documentation-lookup

Fetch current library, framework, or API documentation via Context7 MCP.

Community
Intermediate