best practices

Bilingual

Good CLI Design Is Mostly Silence
2 months ago
- A good CLI knows when to be silent; output is an interface, not decoration.
- The --quiet flag should mean print nothing on success unless there is something important; it should not just reduce messages.
- stdout is for data/results; stderr is for logs, warnings, and diagnostics. Never mix them.
- Color output must be controllable via --color=auto/always/never, with auto as default (color only when stdout is a terminal).
- Exit codes are part of the API and should be meaningful (e.g., 0 for success, 1 for diff found, 2 for failure).
- Human-readable output and machine-readable output (JSON) should be separate; JSON is a contract that should not change.
- Hints for next commands should be short and optional; they should not appear in quiet mode, JSON output, or when stdout contains data.
- Silence gives control back to the user, building trust in the tool.
The Ten Commandments for C Programmers from Henry Spencer (Unix/Plan 9 – 1987)
2 months ago
- Run lint frequently and study its output carefully.
- Never dereference a null pointer.
- Cast function arguments to expected types explicitly.
- Declare library function return types if headers are missing.
- Check array bounds and avoid using gets().
- Always check error return codes from functions.
- Study and reuse libraries instead of reinventing them.
- Use the K&R brace style for clarity and consistency.
- Ensure external identifiers are unique in the first six characters.
- Write portable code; avoid assuming a specific architecture.
just surf
2 months ago
- There are many conflicting opinions on best practices for coding agents, such as planning versus execution, context management, and MCP usage.
- Advice often becomes outdated as technology improves, with updates indicating that earlier tips are no longer relevant.
- The key message is to stop having rigid opinions and instead adapt to the changing landscape, symbolized by 'just surf'.
Agents.md – Dumb Human
2 months ago
- Assume the human operator might be mistaken about anything.
- The user likely has little knowledge of the codebase, language, architecture, and tools.
- Existing code may be accidental, broken, outdated, or based on misunderstandings.
- User instructions may incorrectly describe the desired outcome.
- Do not blindly obey implementation suggestions; focus on producing the best working result.
- Before changing code, inspect the repository and understand how the system works.
- Verify assumptions from code, tests, documentation, and available tools.
- Prefer simple, robust, idiomatic solutions over complex or broken ones.
- Replace bad solutions with better ones; do not preserve broken architecture just because it exists.
- Never fake success; run builds, tests, linters, and relevant checks whenever possible.
- Act as the senior engineer responsible for the final outcome.
Best Simple System for Now
3 months ago
- The article discusses a dichotomy in software development between 'perfectionism' (building thorough, sustainable systems) and 'pragmatism' (quick, hacky solutions), but proposes a middle path called the Best Simple System for Now (BSSN).
- BSSN is defined as the simplest system that meets current needs, written to an appropriate standard, with no extraneous code and exactly the required robustness. It emphasizes designing 'for now' without anticipating the future.
- Key components of BSSN include: 'for now' (avoiding future speculation), 'simple' (minimizing complexity for current requirements), and 'best' (writing high-quality, intention-revealing code without cutting corners).
- The article argues against common objections to BSSN, such as it being overkill for prototypes, incomplete, or inefficient, by highlighting benefits like early delivery, risk reduction, and adaptability through iterative development.
- Adopting BSSN requires good habits (e.g., avoiding over-engineering), courage to try new approaches, and humility to accept uncertainty. It encourages starting small, focusing on feedback, and evolving systems as needs change.
- Examples illustrate BSSN in practice: a custom JSON marshaling solution for nine entity types and the XStream XML library, both demonstrating simplicity and focused functionality.
- The conclusion emphasizes that BSSN allows for both quality and speed, enabling teams to build replaceable, joyful code (using principles like CUPID) that adapts to changing requirements without unnecessary complexity.

best practices

Good CLI Design Is Mostly Silence

The Ten Commandments for C Programmers from Henry Spencer (Unix/Plan 9 – 1987)

just surf

Agents.md – Dumb Human

Best Simple System for Now