coding-comments
My personal best practices for writing clear and effective code comments.
When & Why to Use This Skill
This Claude skill provides a comprehensive framework for writing clear, professional, and effective code comments. It specifically implements a TypeScript-adapted version of Taylor Otwell's renowned Laravel commenting style, focusing on visual hierarchy and readability. By standardizing how developers document their logic and file headers, it ensures that codebases remain maintainable, aesthetically consistent, and easy to navigate for engineering teams.
Use Cases
- Standardizing Team Documentation: Establish a unified commenting standard across a development team to ensure all source files follow the same professional formatting.
- Improving Code Readability: Use structured multi-line comment blocks to break down complex logic, making it easier for peer reviewers to understand the intent behind the code.
- Professionalizing Open Source Projects: Apply high-quality documentation patterns to public-facing repositories to improve project credibility and contributor onboarding.
- Automated Style Enforcement: Integrate these best practices into AI-driven code generation workflows to ensure generated code meets specific organizational style guides.
| name | coding-comments |
|---|---|
| description | My personal best practices for writing clear and effective code comments. |
Coding Comments
Gotchas
- When creating source code file top-level descriptions, do not use
//ABOUTME: <etc>format. Instead, use Taylor Otwells commenting style (adapted to typescript comments, instead of php).
/*
|------------------------------------------------------------------------------
| Heading: How to write your code comments like Taylor
|------------------------------------------------------------------------------
|
| In Laravel, there are 598 three-line code comments. The first line of each
| is ~74 characters long. Each subsequent line has three characters fewer
| than the one above it. Whether trailing periods count is your choice.
|
| Descriptions proceeding the first very-specifically-formatted line can be
| any length you want, and can have multiple paragraphs.
| - Also, optional dot points
|
*/