ZacharyZhang-NY
e74dafcd36
Three independently ugly bugs that all fed the same log flood:
* Electron's `WebFrameMain.send` writes every "Render frame was disposed"
to stderr via `console.error`. When the worker fans a second
agent-event past a reloading renderer, we produced thousands of
identical lines and stalled the main loop on stderr I/O. Added a
`mainFrame.detached` guard so the send is short-circuited before
Electron's own catch block fires, and installed a targeted filter in
`suppress-warnings.ts` (now actually imported from the entry point)
so the specific `console.error("Error sending from webFrameMain:"…)`
noise never reaches the terminal. Any other payload still surfaces.
* `dispatchAgentMessage` accepted the human-reader sentinel as a wake
target when an agent replied to `__board__` — `wakeAgentIfPossible`
then called `db.getAgent("__board__")`, threw, and the dispatcher
kept repeating on every send. Strip `HUMAN_SENDER_ID` at
`resolveMessageWakeTargets`, and keep a defense-in-depth guard in the
heartbeat so a stray caller (future automation fan-out) cannot
reintroduce the crash.
* Pi's skills loader rejects any SKILL.md whose frontmatter `name`
diverges from its parent directory. The four bundled `my-writing-style`
copies declared `name: writing-style-skill`, so every install emitted
a warning and dropped the skill. They also lived as orphan gitlinks
(mode 160000 without .gitmodules), and the global `*.md` gitignore
hid every other SKILL.md from version control. Fixed the frontmatter
to match the dir, converted the dangling submodules to plain trees,
and allowlisted `builtin-skills/**/*.md` so a fresh clone carries the
catalogue instead of silently losing it.
137 lines
3.2 KiB
Markdown
137 lines
3.2 KiB
Markdown
---
|
|
name: clean-names
|
|
description: Use when naming, renaming, or fixing names of variables, functions, classes, or modules in Python. Enforces Clean Code principles—descriptive names, appropriate length, no encodings.
|
|
---
|
|
|
|
# Clean Names
|
|
|
|
## N1: Choose Descriptive Names
|
|
|
|
Names should reveal intent. If a name requires a comment, it doesn't reveal its intent.
|
|
|
|
```python
|
|
# Bad - what is d?
|
|
d = 86400
|
|
|
|
# Good - obvious meaning
|
|
SECONDS_PER_DAY = 86400
|
|
|
|
# Bad - what does this function do?
|
|
def proc(lst):
|
|
return [x for x in lst if x > 0]
|
|
|
|
# Good - intent is clear
|
|
def filter_positive_numbers(numbers):
|
|
return [n for n in numbers if n > 0]
|
|
```
|
|
|
|
## N2: Choose Names at the Appropriate Level of Abstraction
|
|
|
|
Don't pick names that communicate implementation; choose names that reflect the level of abstraction of the class or function.
|
|
|
|
```python
|
|
# Bad - too implementation-specific
|
|
def get_dict_of_user_ids_to_names():
|
|
...
|
|
|
|
# Good - abstracts the data structure
|
|
def get_user_directory():
|
|
...
|
|
```
|
|
|
|
## N3: Use Standard Nomenclature Where Possible
|
|
|
|
Use terms from the domain, design patterns, or well-known conventions.
|
|
|
|
```python
|
|
# Good - uses pattern name
|
|
class UserFactory:
|
|
def create(self, data): ...
|
|
|
|
# Good - uses domain term
|
|
def calculate_amortization(principal, rate, term): ...
|
|
```
|
|
|
|
## N4: Unambiguous Names
|
|
|
|
Choose names that make the workings of a function or variable unambiguous.
|
|
|
|
```python
|
|
# Bad - ambiguous
|
|
def rename(old, new):
|
|
...
|
|
|
|
# Good - clear what's being renamed
|
|
def rename_file(old_path: Path, new_path: Path):
|
|
...
|
|
```
|
|
|
|
## N5: Use Longer Names for Longer Scopes
|
|
|
|
Short names are fine for tiny scopes. Longer scopes need longer, more descriptive names.
|
|
|
|
```python
|
|
# Good - short name for tiny scope
|
|
total = sum(x for x in numbers)
|
|
|
|
# Good - longer name for module-level constant
|
|
MAX_RETRY_ATTEMPTS_BEFORE_FAILURE = 5
|
|
|
|
# Bad - short name at module level
|
|
MAX = 5
|
|
```
|
|
|
|
## N6: Avoid Encodings
|
|
|
|
Don't encode type or scope information into names. Modern editors make this unnecessary.
|
|
|
|
```python
|
|
# Bad - Hungarian notation
|
|
str_name = "Alice"
|
|
lst_users = []
|
|
i_count = 0
|
|
|
|
# Good - clean names
|
|
name = "Alice"
|
|
users = []
|
|
count = 0
|
|
|
|
# Bad - interface prefix
|
|
class IUserRepository:
|
|
...
|
|
|
|
# Good - just name it
|
|
class UserRepository:
|
|
...
|
|
```
|
|
|
|
## N7: Names Should Describe Side Effects
|
|
|
|
If a function does something beyond what its name suggests, the name is misleading.
|
|
|
|
```python
|
|
# Bad - name doesn't mention file creation
|
|
def get_config():
|
|
if not config_path.exists():
|
|
config_path.write_text("{}") # Hidden side effect!
|
|
return json.loads(config_path.read_text())
|
|
|
|
# Good - name reveals behavior
|
|
def get_or_create_config():
|
|
if not config_path.exists():
|
|
config_path.write_text("{}")
|
|
return json.loads(config_path.read_text())
|
|
```
|
|
|
|
## Quick Reference
|
|
|
|
| Rule | Principle | Example |
|
|
|------|-----------|---------|
|
|
| N1 | Descriptive names | `SECONDS_PER_DAY` not `d` |
|
|
| N2 | Right abstraction level | `get_user_directory()` not `get_dict_of_...` |
|
|
| N3 | Standard nomenclature | `UserFactory`, `calculate_amortization` |
|
|
| N4 | Unambiguous | `rename_file(old_path, new_path)` |
|
|
| N5 | Length matches scope | Short for loops, long for globals |
|
|
| N6 | No encodings | `users` not `lst_users` |
|
|
| N7 | Describe side effects | `get_or_create_config()` |
|