write-comments
/write-comments
Stosuje konwencje komentarzy w kodzie TypeScript, Pythonie i innych językach: kiedy komentować, jak podpisywać sekcje i czego unikać.
- Autor
- organizzolini ↗
- Repozytorium
- codebase ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 26.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 1
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 26.10.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
Co robi i kiedy
Stosuje konwencje komentarzy w kodzie TypeScript, Pythonie i innych językach: kiedy komentować, jak podpisywać sekcje i czego unikać.
Oryginalny opis (EN)
Apply codebase commenting conventions for TypeScript, Python, and any language. USE WHEN writing or reviewing comments, adding section comments, organizing code into logical groups, or asked about comment style. Covers when to comment, how to write good comments, section comment format (emoji + capitalized name), emoji reference table, and anti-patterns to avoid (obvious comments, redundant JSDoc, TODO lint bypasses, dash-line dividers).
Jak działa
- When to Comment
- How to Comment
- Anti-Patterns
- Section Comments
Podgląd SKILL.md
---
name: write-comments
description: Apply codebase commenting conventions for TypeScript, Python, and any language. USE WHEN writing or reviewing comments, adding section comments, organizing code into logical groups, or asked about comment style. Covers when to comment, how to write good comments, section comment format (emoji + capitalized name), emoji reference table, and anti-patterns to avoid (obvious comments, redundant JSDoc, TODO lint bypasses, dash-line dividers).
license: MIT
---
# Commenting
## When to Comment
Code should be self-explanatory through good naming. Comments add value only when they explain **why** something is done — not **what** it does.
**Comment when:**
- Explaining non-obvious intent or business logic
- Documenting known edge cases or external constraints
- Noting a workaround with a link to the upstream issue
**Don't comment when:**
- The code is clear from reading it
- You're narrating what the code obviously does
## How to Comment
### Good Comments
```typescript
// Delay is intentional: the third-party API enforces a 1s rate limit per key
await delay(1000);
// Uses linear search because this list is always < 10 items and never hot
const found = items.find((item) => item.id === targetId);
```
### Bad Comments
```typescript
// Increment counter
counter++;
// Call the API
const result = await fetchData();
// Return the value
return value;
```
## Anti-Patterns
### Obvious Comments
```typescript
// Bad: restates what the code already says
const user = getUser(id); // Get the user by id
```
### Redundant JSDoc
Avoid JSDoc on private functions or functions whose signature is self-documenting.
```typescript
// Bad: JSDoc that adds nothing
/**
* Gets the user.
* @param id - The user id.
* @returns The user.
*/
function getUser(id: string): User { ... }
// Good: JSDoc only when it adds non-obvious context
/**
* Returns the user record, or throws `UserNotFoundError` if the id is
* not present in the active-users projection. Does NOT check the archive.
*/
function getUser(id: string): User { ... }
```
### TODO Comments
Don't leave TODO comments to bypass lint rules or defer real fixes.
```typescript
// Bad: silences a rule without explanation
// eslint-disable-next-line @typescript-eslint/no-explicit-any
function process(data: any) { ... }
// Good: fix the underlying issue instead
function process(data: unknown) { ... }
```
If a TODO is genuinely needed (tracked work), include a ticket reference:
```typescript
// TODO(#1234): remove once the upstream API supports batch deletes
```
### Divider Comments
```typescript
// Bad: dash dividers
// ---------------------------------------------------------------------------
// Configuration
// ---------------------------------------------------------------------------
// Bad: equals dividers
// ===========================
// Configuration
// ===========================
// Bad: plain section label with no emoji
// Configuration
// Bad: #region blocks
//#region 🔧 Configuration
//#endregion
```
Use emoji section comments instead — see [Section Comments](#section-comments) below.
## Section Comments
When a file benefits from logical groupings, mark each section with a single-line emoji comment.
### Format
```text
// <emoji> <Section name>
```
- **Emoji first** — conveys purpose at a glance
- **Capital first letter** — `// 🔧 Configuration`, not `// 🔧 configuration`
- **Single line** — no closing marker, no surrounding dash lines
- **Python** uses `#` instead of `//` — same rules otherwise
### Examples
#### TypeScript / JavaScript
```typescript
// 🔧 Configuration
const MAX_RETRIES = 3;
const API_TIMEOUT = 5_000;
// 🎭 Mocks
vi.mock("./api.js");
// 🧪 Tests
describe("MyService", () => { ... });
```
#### NestJS service layout
```typescript
@Injectable()
export class MyService {
// 🏗 Dependency injection
constructor(private readonly logger: LoggerService) {}
// 🔐 Private fields
// 🔑 Public fields
// 🔏 Private methods
// 🌎 Public methods
}
```
#### Python
```python
# 🔧 Configuration
MAX_RETRIES = 3
# 🧪 Tests
class TestMyService(unittest.TestCase): ...
```
### Emoji Reference
| Emoji | Typical use |
| ----- | ----------- |
| 🏗 | Dependency injection, constructors |
| 🔧 | Configuration, constants |
| 🗄️ | Types, data structures |
| 🏷️ | Type aliases, interfaces |
| ♟️ | Constants module |
| 🔐 | Private fields |
| 🔑 | Public fields |
| 🔏 | Private methods |
| 🌎 | Public methods |
| 🎭 | Mocks |
| 🧪 | Tests |
| 🔗 | Relations, associations, links |
| 🔎 | Queries |
| 🖋️ | Mutations |
| 📋 | Headings, lists |
| 📦 | Code blocks, packages |
| 📝 | Paragraphs, docs |
| 🖼️ | Images |
| ✏️ | Inline formatting |
| ✅ | Completed / passing |
| ➖ | Thematic breaks |
| 💬 | Blockquotes |
| 📊 | Tables |
| 📚 | Grammar groups, large topic areas |
### Rules Summary
1. Format: `// <emoji> <Section name>` (TypeScript/JS) or `# <emoji> <Section name>` (Python)
2. Section name: capitalized first letter, short noun phrase
3. Never wrap a section comment in dash lines or any other delimiter
4. Never use `#region`/`#endregion` — plain emoji comments are sufficient
5. Choose an emoji that conveys the section's purpose; consult the table above
Wersje
W bazie nie ma innych skilli o nazwie write-comments.
Migawka bazy z 13.11.2026 · wersja paczki c21e40d54246 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100accelint-ts-documentation
Audytuje i poprawia dokumentację JavaScript i TypeScript: komentarze JSDoc, znaczniki TODO i FIXME oraz jakość komentarzy w kodzie. - 90dev-code-comment-style
Podpowiada zasady pisania komentarzy w kodzie w 16 językach na podstawie wytycznych Google, także docstringów i JSDoc. - 100wise-code-comments
Pilnuje zasad pisania komentarzy i docstringów w kodzie we wszystkich językach programowania, przy dodawaniu i przeglądzie. - 100code-comments
Wyodrębnia lokalizacje komentarzy z plików kodu do analizy, przy czyszczeniu komentarzy, audycie dokumentacji i analizie wzorców komentowania w różnych językach. - 100code-comment-style
Pisze i skraca komentarze w kodzie tak, by w 1-3 linijkach podawały powód lub niezmiennik. - 100document-code
Stosuje standardy dokumentowania Google Style w kodzie Python, Go, TypeScript i Terraform: docstringi, komentarze, JSDoc oraz opisy zmiennych i wyjść Terraform.