skills.rest
salverius-tech
salverius-techCOMMUNITY
Explore all skills by this author →
GitHub

code-documentation

Guide developers in writing self-explanatory code and meaningful comments.

Updated Apr 11, 2023
Search Tags:#best practices#documentation#maintainability#comments#docstrings#code clarity
One-click install
npx skills add https://github.com/salverius-tech/dotfiles --skill code-documentation-salverius-tech
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: code-documentation
Source: https://github.com/salverius-tech/dotfiles/tree/main/home/dot_claude/skills/code-documentation
Command: npx skills add https://github.com/salverius-tech/dotfiles --skill code-documentation-salverius-tech

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This Skill helps developers write code that is easier to understand, maintain, and debug by providing guidelines on effective commenting and promoting self-explanatory code.

Core Features & Use Cases

  • Comment Best Practices: Learn when and how to write comments, avoiding common anti-patterns.
  • Self-Explanatory Code: Understand how to structure code for maximum readability.
  • Use Case: When you're unsure if a complex piece of logic needs a comment, or if a comment is actually hindering understanding, consult this Skill for guidance on refactoring or writing better explanations.

Quick Start

Use the code-documentation skill to understand the best practices for writing Python docstrings.

Frequently Asked Questions about code-documentation

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

FAQPage Schema
When should I write comments in my code versus making it self-explanatory?▼

Write comments to explain the 'why' behind complex logic rather than the 'what'. Default to self-explanatory code, using a decision framework to determine when comments are necessary for maintainability.

How do I write effective Python docstrings for code maintainability?▼

Write effective Python docstrings by following language-specific guidelines that focus on explaining purpose and intent. This improves code clarity and ensures functions are easier to maintain and debug.

What are common code commenting anti-patterns I should avoid?▼

Common commenting anti-patterns include stating the obvious, restating code logic, and writing outdated explanations. This Skill provides guidelines to identify and refactor these hindrances for better code readability.

Does this documentation skill provide examples for JavaScript and TypeScript?▼

Yes, the documentation skill provides language-specific examples for JavaScript and TypeScript. It includes guidelines on writing meaningful comments to improve code clarity across these languages.

How do I refactor complex logic that hinders code understanding?▼

Refactor complex logic by structuring code for maximum readability and applying a decision framework for comment necessity. This helps determine if a comment is needed or if the code itself can be clearer.

Related Skills

Explore More Software Engineering Skills→
sadie100sadie100

edit-article

Divide articles into sections and refine prose clarity and flow.

Community
Intermediate
oimiragieooimiragieo
36

doc-generator

Generate API documentation, developer guides, and OpenAPI/Swagger specs from code.

Community
Advanced
yonyon
3

lint

Run linters and static analysis tools with severity-based output and auto-fix mode.

Community
Basic
masrurimzmasrurimz

doc-writer

Generate JSDoc/TSDoc comments, READMEs, and API documentation across codebases.

Community
Basic