Bilingual

On Long Term Software Development - Bert Hubert's writings
a day ago
- Limit and carefully audit dependencies; avoid thousands of small dependencies.
- Invest heavily in testing to catch regressions from shifting dependencies and enable refactoring.
- Keep code simple and boring; refactor early and often to manage complexity.
- Document not only code but also design philosophy, rationale, and architecture.
- Maintain a stable, long-term team of employees rather than relying on consultants.
- Consider open-sourcing code to enforce higher standards and gain external scrutiny.
- Implement thorough logging and telemetry from the start for debugging and performance monitoring.
- Periodically review dependencies for changes, security issues, or new capabilities.
- Avoid hype-driven technology choices; prefer proven, long-lived solutions.
Stop Using (only) GitHub Releases
a day ago
- The author accidentally upgraded Rust dependencies and faced difficulties because projects lacked CHANGELOG.md files, relying solely on GitHub releases.
- GitHub releases have downsides: pagination makes cross-referencing hard, they are not part of the repository, and they are at risk of being lost if GitHub declines.
- A CHANGELOG.md file in the repository migrates with the code and should be the primary source of release notes.
- The principle extends beyond changelogs: commit messages should explain why changes were made, documentation should be in markdown files, and any project-related data expressible as files should be stored as files in the repository.
Command Line Interface Guidelines
17 days ago
- A guide to designing modern command-line programs, balancing traditional UNIX principles with human-centric improvements.
- Authors include Aanand Prasad, Ben Firshman, Carl Tashian, and Eva Parish, with contributions from other industry experts.
- The guide advocates for human-first design, emphasizing usability, discoverability, and empathy without sacrificing UNIX composability and consistency.
- Key guidelines include using argument parsing libraries, providing extensive help text, sending primary output to stdout and errors to stderr.
- Output should be human-readable by default, with machine-readable options like --json, and use color, formatting, and emoji intentionally.
- Errors should be caught and rewritten for clarity, with suggestions for corrections and easy bug reporting.
- Arguments and flags should follow standards, prefer flags over args for clarity, and avoid secrets in flags for security.
- Interactivity should only occur in TTY contexts, with prompts and confirmations for dangerous actions, and clear escape mechanisms.
- Subcommands should be consistent and avoid ambiguous names, with robustness features like input validation, timeouts, and parallel execution.
- Configuration follows a precedence order (flags > env variables > config files), and distribution should favor single binaries with easy uninstallation.
- Analytics collection requires explicit consent or opt-out transparency, with alternatives like web docs and user feedback recommended.
Write code like a human will maintain it
19 days ago
- LLMs can write code for you, reducing manual effort but leading to duplicated logic.
- Repeated conditional checks in different files create maintenance issues.
- LLMs learn from existing code patterns, reinforcing bad practices if shortcuts are used.
- Duplicated code signals the model to continue the same style.
- Code smells accumulate, making it hard to prompt the LLM to fix issues later.
- LLMs don't operate in a vacuum; they mimic the codebase's patterns.
- Maintenance becomes challenging as bad habits are reinforced.
- Writing maintainable code is crucial because LLMs absorb and replicate what they see.

Hasty Briefsbeta

best-practices

On Long Term Software Development - Bert Hubert's writings

Stop Using (only) GitHub Releases

Command Line Interface Guidelines

Write code like a human will maintain it