diff --git a/docs/article-summaries/README.md b/docs/article-summaries/README.md new file mode 100644 index 0000000..5469236 --- /dev/null +++ b/docs/article-summaries/README.md @@ -0,0 +1,220 @@ +# Article Summaries Collection + +This directory contains comprehensive summaries of articles and resources related to software development best practices, compiled from [calcipy issue #38](https://github.com/KyleKing/calcipy/issues/38). + +## Overview + +These documents synthesize insights from 29+ articles covering various aspects of professional software development, from code quality and testing to team collaboration and project management. + +## Documents + +### [1. Logging Best Practices](./logging-best-practices.md) +**Topics Covered:** +- Log level guidelines (ERROR, WARN, INFO, DEBUG, TRACE) +- The "2AM rule" for error logging +- Production support and forensic analysis +- Making logs actionable with proper context + +**Key Takeaway:** Logs should serve production support and forensic analysis, with levels chosen based on required response rather than perceived importance. + +--- + +### [2. Development & Debugging](./development-and-debugging.md) +**Topics Covered:** +- Systematic bug-fixing approach (5 phases) +- Functions vs. classes design principles +- Python debugging techniques +- Making debugging a learnable skill + +**Key Takeaway:** Quality development is achievable through disciplined practices, automation, and acknowledging human limitations—not innate genius. + +--- + +### [3. Testing Best Practices](./testing-best-practices.md) +**Topics Covered:** +- Python testing style guide +- Stubbing vs. mocking strategies +- Test organization and naming +- Preferring real objects over mocks + +**Key Takeaway:** Focus on testing behavior rather than implementation, use real objects when practical, and always use autospec for mocks. + +--- + +### [4. Code Review & Pull Request Best Practices](./code-review-and-pr-best-practices.md) +**Topics Covered:** +- Minimal, focused pull requests +- Code review guidelines for reviewers and authors +- Team collaboration in reviews +- Avoiding process bottlenecks + +**Key Takeaway:** Every PR should have one unique goal with minimal changes; reviews are about collaboration and learning, not gatekeeping. + +--- + +### [5. README Best Practices](./readme-best-practices.md) +**Topics Covered:** +- Essential README sections +- Writing style and formatting +- Visual elements and documentation +- README as a filtering tool + +**Key Takeaway:** A great README welcomes newcomers, informs quickly, guides through setup, invites contribution, and maintains accuracy over time. + +--- + +### [6. GitHub & Team Practices](./github-and-team-practices.md) +**Topics Covered:** +- Professional GitHub workflow +- Issue and label management +- Team collaboration patterns +- Automation and tooling + +**Key Takeaway:** Use GitHub as a communication platform to enable precise technical communication inexpensively and reduce wasted development time. + +--- + +### [7. Python Best Practices](./python-best-practices.md) +**Topics Covered:** +- PEP 8 and code style +- Common Python idioms +- Modern tooling (Poetry, Black, mypy) +- Project structure and configuration + +**Key Takeaway:** Follow community conventions with automated tools, prefer explicitness over cleverness, and use modern tooling for quality assurance. + +--- + +## Articles by Category + +### Logging (4 articles) +1. [Logging levels: the wrong abstraction | IG Labs](https://labs.ig.com/logging-level-wrong-abstraction) +2. [Log Levels - Stack Overflow](https://stackoverflow.com/questions/7839565/logging-levels-logback-rule-of-thumb-to-assign-log-levels/8021604#8021604) +3. [What should you log in an application](https://cloudncode.blog/2016/12/30/what-should-you-log-in-an-application-and-how-to-avoid-having-24x7-support-looking-at-them/) +4. [How to Log in Python Like a Pro](https://guicommits.com/how-to-log-in-python-like-a-pro/) + +### Development & Debugging (4 articles) +5. [How to fix a bug](https://sobolevn.me/2019/01/how-to-fix-a-bug) +6. [Mediocre Developer](https://sobolevn.me/2018/03/mediocre-developer) +7. [Regex visualization](https://regexper.com/) +8. [Debugging Scripts Guide](https://geo-python.github.io/2017/lessons/L6/debugging-scripts.html) +9. [Debugging Series 2021](https://thoughtbot.com/blog/debugging-series-2021-welcome-to-the-jungle) + +### Testing (2 articles) +10. [Stubbing vs Mocking](https://outsidein.dev/testing-concepts.html#stubbing-and-mocking) +11. [Testing the Diff](https://www.vinta.com.br/blog/2021/testing-the-diff/) +12. [Python Testing Style Guide](https://blog.thea.codes/my-python-testing-style-guide/) + +### Code Review & Best Practices (4 articles) +13. [Code Review Best Practices](https://www.kevinlondon.com/2015/05/05/code-review-best-practices.html) +14. [PR Guidelines](https://gist.github.com/mherrmann/5ce21814789152c17abd91c0b3eaadca) +15. [One of the Team](https://python-hyper.org/en/latest/one-of-the-team.html) +16. [Code Review Comments (Go)](https://github.com/golang/go/wiki/CodeReviewComments) +17. [Out of Control Review Processes](https://apenwarr.ca/log/20171213) +18. [Software Quality Metrics](https://hub.codebeat.co/docs/software-quality-metrics) + +### README Resources (5 articles) +19. [README Checklist](https://liw.fi/readme-review/) +20. [Software Release Practice HOWTO](https://tldp.org/HOWTO/Software-Release-Practice-HOWTO/distpractice.html#readme) +21. [Awesome README](https://github.com/matiassingers/awesome-readme) +22. [Make a README](https://www.makeareadme.com/) +23. [Best README Template](https://github.com/othneildrew/Best-README-Template) + +### GitHub & Team Practices (4 articles) +24. [Using GitHub Professionally](https://petabridge.com/blog/use-github-professionally/) +25. [Sane GitHub Labels](https://medium.com/@dave_lunny/sane-github-labels-c5d2e6004b63) +26. [Triage Process](https://github.com/vector-im/element-meta/wiki/triage-process) +27. [Every Programmer Should Know](https://github.com/mtdvio/every-programmer-should-know) + +### Python Best Practices (2 articles) +28. [Python Style Guide](https://docs.python-guide.org/writing/style/) +29. [Python Package Template](https://github.com/TezRomacH/python-package-template) + +--- + +## Key Themes Across All Resources + +### Quality Through Process +- Systematic approaches beat ad-hoc solutions +- Automation reduces human error +- Documentation builds institutional knowledge +- Testing prevents regressions + +### Communication is Critical +- Clear commit messages and PR descriptions +- Comprehensive READMEs for onboarding +- Code reviews as collaborative learning +- Issues and labels for project organization + +### Simplicity and Clarity +- Prefer simple solutions over clever ones +- Code should be self-documenting +- Minimize cognitive load for readers +- Follow established conventions + +### Continuous Improvement +- Regular refactoring +- Learning from bugs and incidents +- Iterative development processes +- Measuring and adjusting practices + +### Human-Centered Development +- Blameless postmortems +- Respectful code reviews +- Inclusive documentation +- Work-life balance awareness + +--- + +## Using These Resources + +### For Individual Developers +- **Starting a new project?** Check the README and Python best practices guides +- **Fixing a bug?** Follow the systematic approach in Development & Debugging +- **Writing tests?** Consult the Testing best practices +- **Submitting a PR?** Review the Code Review guidelines +- **Setting up logging?** Use the Logging best practices + +### For Teams +- **Establishing processes?** Review GitHub & Team Practices +- **Onboarding new members?** Share the README best practices +- **Improving code quality?** Implement practices from Code Review and Python guides +- **Building culture?** Apply lessons from Team Practices and Every Programmer Should Know + +### For Project Maintainers +- **Creating documentation?** Use the README and documentation guides +- **Managing issues?** Check GitHub practices for labels and triage +- **Reviewing PRs?** Follow Code Review best practices +- **Setting standards?** Combine Python and Testing best practices + +--- + +## Note on Article Accessibility + +Some articles were not accessible during the summarization process due to network issues, 403/404 errors, or SSL handshake failures. Where articles were inaccessible, the summaries include notes about typical content in that category and common best practices. + +Successfully summarized articles include key quotes and detailed insights from the original sources. + +--- + +## Contributing + +These summaries were created to capture learnings from valuable resources. If you: +- Find broken links +- Have updated information +- Want to add new relevant articles +- Spot errors or omissions + +Please open an issue or submit a pull request to improve these resources. + +--- + +## License + +These summaries are provided for educational purposes. Original articles retain their respective copyrights and licenses. Please refer to the original sources for authoritative information and proper attribution. + +--- + +**Last Updated:** 2025-11-20 + +**Source Issue:** [calcipy#38](https://github.com/KyleKing/calcipy/issues/38) diff --git a/docs/article-summaries/code-review-and-pr-best-practices.md b/docs/article-summaries/code-review-and-pr-best-practices.md new file mode 100644 index 0000000..a20af07 --- /dev/null +++ b/docs/article-summaries/code-review-and-pr-best-practices.md @@ -0,0 +1,231 @@ +# Code Review & Pull Request Best Practices + +A collection of best practices for code reviews and pull request management. + +## Overview + +This document compiles insights on conducting effective code reviews, submitting quality pull requests, and maintaining high code quality through peer review processes. + +--- + +## Good PRs Are Minimal + +**Source:** [PR Guidelines](https://gist.github.com/mherrmann/5ce21814789152c17abd91c0b3eaadca) + +### Core Principle +"Every PR should have one, and only one, unique goal." Contributors should make the absolute minimum changes necessary to achieve that single objective. + +### Specific Guidelines + +**What to Avoid:** +- Unnecessary whitespace modifications (tabs/spaces conversions create excessive line changes) +- Running linters across the entire codebase as a side effect +- Introducing new tools or dependencies unless absolutely essential +- Deviating from the project's established code style + +**What to Follow:** +- Match existing conventions for tabs/spaces, line length limits, and quote styles +- Keep changes focused and reviewable +- Submit multiple improvements as separate PRs rather than combining them + +### The Rationale + +The maintainer emphasizes that reviewers must examine every change you make. A minimal, focused PR is easier to understand, review, and approve. This approach respects the reviewer's limited time and demonstrates consideration for the maintenance burden your contribution creates. + +**Key Takeaway:** Quality PRs prioritize clarity and minimalism over comprehensiveness in a single submission. + +--- + +## Code Review Best Practices + +**Source:** [Code Review Best Practices - Kevin London](https://www.kevinlondon.com/2015/05/05/code-review-best-practices.html) + +*Note: This article was not accessible during summarization. Common code review best practices include:* + +### For Reviewers +- **Be Kind and Constructive**: Frame feedback positively +- **Ask Questions**: "What do you think about...?" vs "This is wrong" +- **Provide Context**: Explain why something matters +- **Praise Good Code**: Acknowledge clever solutions or improvements +- **Review Thoroughly**: Don't rubber-stamp; actually read the code +- **Use Checklists**: Ensure consistent review quality + +### For Authors +- **Keep PRs Small**: Easier to review, faster to merge +- **Provide Context**: Explain the why, not just the what +- **Self-Review First**: Catch obvious issues before requesting review +- **Respond Promptly**: Keep the review cycle moving +- **Be Open to Feedback**: Remember reviews improve code quality + +### Review Focus Areas +1. **Functionality**: Does the code do what it's supposed to? +2. **Tests**: Are there sufficient tests? Do they test the right things? +3. **Design**: Is the approach sound? Are there better alternatives? +4. **Complexity**: Is the code as simple as it can be? +5. **Naming**: Are variables, functions, and classes well-named? +6. **Documentation**: Are complex parts explained? +7. **Security**: Are there potential vulnerabilities? +8. **Performance**: Are there obvious performance issues? + +--- + +## Code Review Comments (Go Wiki, Generally Applicable) + +**Source:** [Go Wiki - Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments) + +*Note: This article was not accessible during summarization. While Go-specific, many principles apply universally:* + +### General Principles +- **Consistency**: Follow established patterns in the codebase +- **Clarity**: Prefer obvious code over clever code +- **Error Handling**: Handle errors explicitly and appropriately +- **Context**: Pass context through call chains when needed +- **Naming**: Use clear, descriptive names; avoid abbreviations + +### Common Review Points +- Variable shadowing issues +- Error return conventions +- Interface design principles +- Package organization +- Comment formatting and content +- Import grouping and ordering + +--- + +## Out of Control Review Processes + +**Source:** [Talk on out of control review processes](https://apenwarr.ca/log/20171213) + +*Note: This article was not accessible during summarization. Common themes in this type of discussion:* + +### When Review Processes Fail +- Too many required reviewers creates bottlenecks +- Perfectionism prevents shipping +- Trivial changes receive disproportionate scrutiny +- Review becomes gatekeeping rather than collaboration +- Inconsistent standards across reviewers + +### Fixing Broken Processes +- **Time-box Reviews**: Set reasonable review time limits +- **Trust and Autonomy**: Empower developers to make decisions +- **Tiered Review**: Match review rigor to change importance +- **Clear Guidelines**: Document what matters in reviews +- **Measure Impact**: Track review time vs. bug rates +- **Culture Change**: Foster collaboration, not gatekeeping + +--- + +## Software Quality Metrics + +**Source:** [Software Quality Metrics](https://hub.codebeat.co/docs/software-quality-metrics) + +*Note: This article was not accessible during summarization. Common quality metrics include:* + +### Code Quality Metrics +- **Complexity**: Cyclomatic complexity, cognitive complexity +- **Duplication**: Code clone detection +- **Coverage**: Test coverage percentages +- **Debt**: Technical debt indicators +- **Churn**: Frequency of changes to files (instability indicator) + +### Using Metrics in Reviews +- Identify high-complexity functions needing refactoring +- Track coverage trends +- Flag excessive duplication +- Prioritize review attention on high-churn, high-complexity areas + +### Metrics Limitations +- Metrics are indicators, not absolute measures +- Context matters more than raw numbers +- 100% coverage doesn't mean bug-free code +- Low complexity can still be poorly designed + +--- + +## Team Collaboration & Pull Request Culture + +**Source:** [One of the Team - Python Hyper](https://python-hyper.org/en/latest/one-of-the-team.html) + +The Hyper project establishes a community-focused approach to open source development with tiered contribution levels: + +### Contributor Guidelines + +Any developer who commits to a Hyper sub-project automatically joins the contributors team, gaining authority to merge pull requests and manage issues. However, the project emphasizes collaborative responsibility through three key expectations: + +1. **Peer Review Requirements**: Contributors must refrain from merging their own work, as "code review is important, and skipping it is bad." + +2. **Maintainer Approval**: Changes should only be merged after a maintainer or administrator approves them, ensuring alignment with project vision. + +3. **Conduct Standards**: All contributors must follow the project's code of conduct outlined in their contributing policy. + +### Maintainer Role + +Those demonstrating sustained valuable contributions may advance to sub-project maintainer status, gaining direct master branch access and permission management authority. These individuals serve dual roles as "stewards of culture, as much as they are of code," responsible for enforcing policies and fostering an inclusive contributor environment. + +The framework balances distributed decision-making with strategic oversight, acknowledging that "the maintainers are responsible for the 'spirit' of the project" while encouraging widespread participation in the ecosystem. + +--- + +## Best Practices Summary + +### For Submitting PRs +1. **Single Purpose**: One goal per PR +2. **Small Changes**: Easier to review and merge +3. **Self-Review**: Catch issues before requesting review +4. **Good Descriptions**: Explain what, why, and how +5. **Tests Included**: Demonstrate functionality and prevent regressions +6. **Follow Conventions**: Match existing code style +7. **Respond Promptly**: Keep review cycles moving + +### For Reviewing PRs +1. **Be Respectful**: Kind, constructive feedback +2. **Be Thorough**: Actually read and understand the code +3. **Ask Questions**: Seek to understand before criticizing +4. **Acknowledge Good Work**: Positive reinforcement matters +5. **Explain Context**: Help the author learn +6. **Focus on Important Issues**: Don't bikeshed minor style points +7. **Approve or Request Changes**: Don't leave PRs in limbo + +### For Process Management +1. **Set Expectations**: Clear guidelines on what gets reviewed +2. **Time-box Reviews**: Don't let PRs stagnate +3. **Automate Checks**: Use CI for style, tests, linting +4. **Trust the Team**: Enable autonomy within guidelines +5. **Measure and Improve**: Track metrics, adjust process +6. **Foster Collaboration**: Review is learning, not gatekeeping + +### Red Flags in Reviews +- **Rubber Stamping**: Approving without actually reviewing +- **Bikeshedding**: Endless debate over trivial issues +- **Gatekeeping**: Using review as power play +- **Inconsistency**: Different standards for different people +- **Ghosting**: Requesting changes then disappearing +- **Perfectionism**: Blocking over minor improvements + +## Tools and Automation + +### Review Automation +- **Linters**: Automated style checking (flake8, pylint, black) +- **Type Checkers**: Static analysis (mypy, pyright) +- **Security Scanners**: Vulnerability detection (bandit, safety) +- **Coverage Tools**: Test coverage reporting +- **CI/CD**: Automated test running and validation + +### Review Platforms +- **GitHub**: Pull requests, review comments, suggestions +- **GitLab**: Merge requests, inline discussions +- **Gerrit**: Change-based code review +- **Phabricator**: Differential code review + +### Communication +- **Code Comments**: Inline explanations in PRs +- **Conventional Comments**: Standardized comment prefixes (nit, question, suggestion) +- **Review Apps**: Deploy preview environments +- **Status Checks**: Required CI passes before merge + +## Further Reading + +- [Google Engineering Practices - Code Review](https://google.github.io/eng-practices/review/) +- [Effective Code Reviews Without the Pain](https://www.developer.com/tech/article.php/3579756) +- [How to Do Code Reviews Like a Human](https://mtlynch.io/human-code-reviews-1/) +- [The Art of Humanizing Pull Requests](https://blog.dnsimple.com/2016/10/the-art-of-humanizing-pull-requests/) diff --git a/docs/article-summaries/development-and-debugging.md b/docs/article-summaries/development-and-debugging.md new file mode 100644 index 0000000..488f82b --- /dev/null +++ b/docs/article-summaries/development-and-debugging.md @@ -0,0 +1,128 @@ +# Development & Debugging Best Practices + +A collection of systematic approaches to software development and debugging. + +## Overview + +This document compiles insights on writing better code, debugging methodologies, and becoming a more effective developer. + +--- + +## How to Fix a Bug: A Systematic Approach + +**Source:** [How to fix a bug](https://sobolevn.me/2019/01/how-to-fix-a-bug) + +The article outlines five key phases for addressing software defects: + +### 1. Spotting the Bug +Detection requires awareness of factors like user impact scale, execution environment, and reproducibility difficulty. Tools such as Sentry, Prometheus, and NewRelic help automate discovery. + +### 2. Reporting the Bug +Quality bug submissions should establish "why this is problematic, what should occur instead, why it matters, and reproduction steps." The author emphasizes that "screenshots and gifs rock for systems with UI" while noting that stack traces shouldn't be image-captured. + +### 3. Reproducing the Bug +Engineers must write failing regression tests to confirm the issue programmatically rather than manually. Debuggers and static analysis tools assist in capturing elusive problems. + +### 4. Fixing the Bug +The actual code modification follows once reproduction succeeds and CI builds pass. + +### 5. Documenting via Postmortem +Final documentation captures the non-technical narrative, including what caused the issue, resolution steps, user impact, and timeline—creating institutional knowledge for future teams. + +The author emphasizes that "bugs happen all the time" and advocates for systematic, blameless processes that prevent recurrence through thorough documentation and testing practices. + +--- + +## Functions vs. Classes: Design Principles + +**Source:** [Mediocre Developer](https://sobolevn.me/2018/03/mediocre-developer) + +The author recommends a clear hierarchy: "Prefer pure functions over regular functions" and "Prefer regular functions over classes," only using classes "in a strong need." This approach prioritizes simplicity and cognitive efficiency. + +### What Makes a Good Developer + +According to this piece, excellence isn't about innate genius. Instead, strong developers: + +- **Embrace continuous learning** without expecting magical shortcuts +- **Prioritize simplicity** using the "WTFs/Minute" principle—code should be understandable at first glance +- **Implement safeguards** through testing, static typing, code reviews, and automated checks +- **Automate deployment** with Docker and CI/CD tools to catch environment-specific failures +- **Monitor production** using error tracking and logging services +- **Remain humble**, recognizing that "all software has bugs" and distrusting their own work enough to implement multiple verification layers + +The core message: quality development isn't reserved for the exceptionally talented—it's achievable through disciplined practices, automation, and acknowledging human limitations. + +--- + +## Python Debugging Techniques + +**Source:** [Debugging Python Scripts](https://geo-python.github.io/2017/lessons/L6/debugging-scripts.html) + +Key debugging approaches for Python development: + +### 1. Test with Known Outputs +Create simplified test cases with predictable results. As the material explains, "we need to know the 'answer' the code should produce" to verify correctness. Using small data subsets allows you to manually calculate expected outcomes before running your full program. + +### 2. Ensure Consistent Behavior +"It is a good thing when your code crashes the same way every time you run it." Reproducible errors are easier to isolate and fix than intermittent problems. If your code works sometimes and fails other times, debugging becomes significantly harder. + +### 3. Reduce Execution Time +When dealing with large datasets that cause crashes, test your program on smaller data portions first. This dramatically speeds up the debugging cycle—waiting 30 minutes for a crash makes testing inefficient. + +### 4. Make Small, Tracked Changes +Use version control (like GitHub) to document modifications incrementally. The documentation emphasizes: "change one thing at a time, test the code, and make more changes if needed." This approach isolates which specific alteration caused a problem, rather than making multiple simultaneous changes that obscure the source of errors. + +These strategies collectively reduce debugging time by creating reproducible conditions and enabling systematic problem identification. + +--- + +## Debugging Series: Welcome to the Jungle + +**Source:** [Debugging Series 2021](https://thoughtbot.com/blog/debugging-series-2021-welcome-to-the-jungle) + +This introductory article launches a multi-part debugging series. While it doesn't detail specific approaches, it previews upcoming topics: + +### Planned Coverage +The series will explore "assumptions, charting a course, reading errors, leveraging Git, root causes, classical philosophy, giving up gracefully. And ducks." + +### Key Philosophy +Rather than prescribing solutions, this introduction establishes that debugging is a learnable skill deserving formal instruction—something many developers never receive formally during their education. + +As stated: "a novice can always learn something from the most arcane subject, and a master can always hone their skills by practicing their fundamentals." + +The series positions debugging as a structured discipline worthy of intentional study rather than trial-and-error learning. + +--- + +## Regex Visualization + +**Source:** [Regexper](https://regexper.com/#%28a*%29%2B) + +*Note: This is a tool rather than an article. Regexper provides visual diagrams of regular expressions, making complex patterns easier to understand and debug.* + +Key benefits: +- Visual representation of regex logic flow +- Easier identification of potential issues (e.g., catastrophic backtracking) +- Educational tool for learning regex syntax +- Debugging aid for complex patterns + +--- + +## Summary: Key Debugging Principles + +1. **Systematic Approach**: Follow a structured process from spotting to fixing to documenting +2. **Reproducibility**: Ensure bugs can be consistently reproduced before attempting fixes +3. **Incremental Changes**: Make small, tracked changes to isolate problem sources +4. **Automation**: Use tools and tests to catch issues early +5. **Documentation**: Record findings to build institutional knowledge +6. **Simplicity First**: Prefer simple, understandable code over clever complexity +7. **Testing**: Write regression tests to prevent bugs from returning +8. **Version Control**: Track all changes systematically + +## Related Tools + +- **Error Tracking**: Sentry, Rollbar, Bugsnag +- **Monitoring**: Prometheus, NewRelic, Datadog +- **Debugging**: pdb (Python debugger), IDE debuggers +- **Static Analysis**: mypy, pylint, flake8 +- **Visualization**: Regexper for regex, profilers for performance diff --git a/docs/article-summaries/github-and-team-practices.md b/docs/article-summaries/github-and-team-practices.md new file mode 100644 index 0000000..c687699 --- /dev/null +++ b/docs/article-summaries/github-and-team-practices.md @@ -0,0 +1,401 @@ +# GitHub & Team Practices + +Best practices for using GitHub professionally and managing software projects effectively. + +## Overview + +This document compiles insights on professional GitHub usage, issue management, team collaboration, and project organization. + +--- + +## Using GitHub Professionally + +**Source:** [Using GitHub Professionally](https://petabridge.com/blog/use-github-professionally/) + +### Key Workflow Recommendations + +#### Before Coding: Create Issues First +- File issues to prevent "false starts" and "blind alleys" through early team discussion +- Use issue templates to standardize information collection +- Apply labels sparingly for meaningful organization +- Group related work into milestones to communicate project priorities + +#### During Development: Submit Pull Requests Early +The guide emphasizes: "Don't 'Hold' a Pull Request Until the Job is 'Done'" — submit proposals promptly rather than waiting for completion. + +### Collaboration Techniques + +**Code Discussion:** +- Use GitHub permalinks to reference specific code sections with full context +- Cross-link related issues across pull requests and projects +- Reference issue numbers in commit messages for automatic tracking + +**Pull Request Management:** +- Keep PRs small and focused; break large tasks into independent requests +- Always work on feature branches, never submit from main development branches +- Self-review your own changes first to guide external reviewers + +**Technical Safeguards:** +- Require continuous integration to pass before merging +- Keep branches updated before integrating changes +- Use branch protection rules to maintain code quality + +### Core Philosophy + +The underlying principle centers on leveraging GitHub as a communication platform. As noted, the goal is enabling "precise technical communication inexpensively" to reduce wasted development time and improve team coordination. + +--- + +## Sane GitHub Labels + +**Source:** [Sane GitHub Labels](https://medium.com/@dave_lunny/sane-github-labels-c5d2e6004b63) + +*Note: This article was not accessible during summarization. Common approaches to GitHub label systems:* + +### Label Categories + +**By Type:** +- `bug` - Something isn't working +- `enhancement` - New feature or request +- `documentation` - Documentation improvements +- `refactor` - Code restructuring +- `test` - Test additions or fixes + +**By Priority:** +- `priority: critical` - Must be fixed immediately +- `priority: high` - Important, fix soon +- `priority: medium` - Normal priority +- `priority: low` - Nice to have + +**By Status:** +- `status: blocked` - Waiting on something else +- `status: needs discussion` - Requires team input +- `status: in progress` - Currently being worked on +- `status: ready for review` - Awaiting code review + +**By Area:** +- `area: frontend` - UI/UX changes +- `area: backend` - Server-side logic +- `area: api` - API changes +- `area: database` - Data layer + +### Label Best Practices +- Use colors consistently (red for urgent, yellow for medium, etc.) +- Keep the total number manageable (15-25 labels) +- Document label meanings in CONTRIBUTING.md +- Combine labels rather than creating too many specific ones +- Use label automation with tools like Probot + +--- + +## Triage Process + +**Source:** [Triage Process - Element/Matrix](https://github.com/vector-im/element-meta/wiki/triage-process) + +*Note: This article was not accessible during summarization. Common triage best practices:* + +### Issue Triage Workflow + +**1. Initial Assessment** +- Is this a valid issue? +- Is it a duplicate? +- Is there enough information to act on it? + +**2. Categorization** +- Apply appropriate labels +- Assign to correct project/milestone +- Determine priority + +**3. Response** +- Acknowledge the issue +- Ask for clarification if needed +- Set expectations for resolution + +**4. Assignment** +- Assign to team member if appropriate +- Leave unassigned for community contribution +- Link to related issues or PRs + +### Triage Frequency +- Critical bugs: Immediate +- High priority: Daily +- Normal issues: Weekly +- Low priority: Monthly + +### Closing Issues +- Fixed/resolved +- Won't fix (with explanation) +- Duplicate (link to original) +- Cannot reproduce (after reasonable effort) +- Stale/abandoned + +--- + +## Every Programmer Should Know + +**Source:** [Every Programmer Should Know](https://github.com/mtdvio/every-programmer-should-know) + +This comprehensive resource identifies essential topics every developer should master: + +### Foundational CS Concepts +Algorithms, data structures, complexity analysis (Big O), and number theory form the technical bedrock. + +### System-Level Knowledge +Understanding memory management, latency benchmarks, time/timezone handling, and distributed systems principles is crucial for writing performant code. + +### Practical Skills +String handling (Unicode, encoding), regular expressions, security best practices, and cryptography protect applications from vulnerabilities. + +### Architecture & Design +Developers benefit from learning system design patterns, code organization principles, and evolutionary architecture approaches. + +### Professional Development +The guide emphasizes soft skills—problem-solving, communication, and mental health—alongside career guidance on negotiation, remote work, and technical interviewing. + +### Modern Practices +Topics include testing methodologies, refactoring legacy code, open-source contribution, and emerging disciplines like Platform Engineering focused on developer experience. + +### Continuous Learning +The resource recommends studying academic papers, engaging with coding practice platforms (LeetCode, HackerRank), and exploring multiple programming paradigms. + +The overarching message: becoming an excellent programmer requires balancing deep technical knowledge with practical engineering wisdom and human-centered soft skills. + +--- + +## Team Practices Summary + +### Issue Management + +**Creating Good Issues:** +1. **Clear Title**: Descriptive, specific +2. **Problem Statement**: What's wrong or what's needed +3. **Expected Behavior**: What should happen +4. **Actual Behavior**: What currently happens (for bugs) +5. **Steps to Reproduce**: Clear, numbered steps +6. **Environment**: OS, version, browser, etc. +7. **Screenshots/Logs**: Visual aids when helpful +8. **Acceptance Criteria**: Definition of "done" + +**Issue Templates:** +- Bug report template +- Feature request template +- Documentation improvement template +- Custom templates for project-specific needs + +**Issue Hygiene:** +- Close stale issues (use bots like Stale) +- Keep issues focused on one topic +- Update status with labels +- Link related issues +- Archive obsolete issues + +### Project Organization + +**Milestones:** +- Group related issues +- Set target dates +- Track progress toward goals +- Communicate roadmap + +**Projects (Boards):** +- Kanban-style workflow +- Columns: Backlog, To Do, In Progress, Review, Done +- Automate card movement +- Link issues and PRs + +**Releases:** +- Semantic versioning +- Changelog generation +- Release notes +- Tag strategy + +### Team Communication + +**Commit Messages:** +- Use conventional commits format +- Reference issue numbers +- Explain why, not just what +- Keep first line under 50 characters + +**PR Descriptions:** +- Link to related issues +- Explain approach +- Highlight breaking changes +- Include testing notes +- Add screenshots for UI changes + +**Code Comments:** +- Explain why, not what +- Document non-obvious decisions +- Link to relevant issues/discussions +- Keep comments updated + +### Automation + +**GitHub Actions:** +- CI/CD pipelines +- Automated testing +- Linting and formatting checks +- Dependency updates +- Release automation + +**Bots and Apps:** +- **Dependabot**: Dependency updates +- **Stale**: Close inactive issues +- **Probot**: Custom automation +- **CodeCov**: Coverage reporting +- **Renovate**: Dependency management + +**Branch Protection:** +- Require PR reviews +- Require status checks to pass +- Enforce linear history +- Restrict who can push +- Require signed commits + +### Collaboration Patterns + +**Working Agreements:** +- Define "done" +- Code style guide +- Review expectations +- Response time commitments +- Meeting schedules + +**Communication Channels:** +- GitHub Issues: Project work +- Discussions: Open-ended topics +- Wiki: Documentation +- Slack/Discord: Real-time chat +- Email: External communication + +**Documentation:** +- README: Getting started +- CONTRIBUTING: How to contribute +- CODE_OF_CONDUCT: Community standards +- SECURITY: Reporting vulnerabilities +- Wiki: Detailed guides + +### Remote Team Best Practices + +**Asynchronous Work:** +- Document decisions +- Written communication default +- Flexible working hours +- Clear handoffs +- Over-communicate + +**Time Zones:** +- Schedule overlap hours +- Rotate meeting times +- Record meetings +- Share agendas in advance +- Async standups + +**Building Culture:** +- Virtual social events +- Celebrate wins +- Share learnings +- Pair programming +- Mentorship programs + +--- + +## GitHub Features for Teams + +### Organizations +- Team permissions +- SAML/SSO integration +- Audit logging +- Security policies +- Billing management + +### Team Management +- Nested teams +- Code owner assignments +- Team discussions +- Team mentions +- Permission inheritance + +### Security +- Dependabot alerts +- Code scanning +- Secret scanning +- Security advisories +- Private vulnerability reporting + +### Insights +- Contributor statistics +- Pulse (recent activity) +- Traffic analytics +- Dependency graph +- Network graph + +--- + +## Anti-Patterns to Avoid + +### Issue Management +- Too many labels (confusion) +- No labels (lack of organization) +- Never closing issues (perception of neglect) +- Closing without explanation (frustrating) +- No templates (inconsistent information) + +### Pull Requests +- Massive PRs (hard to review) +- No description (missing context) +- Ignoring CI failures (quality issues) +- Force pushing without warning (lost review comments) +- Merging own PRs without review (bypassing process) + +### Communication +- Only using @mentions (alert fatigue) +- Not linking related items (lost context) +- Vague commit messages (archaeological debugging) +- No documentation updates (stale docs) +- Private decisions (excluding team) + +### Process +- Too much process (bureaucracy) +- Too little process (chaos) +- Inconsistent enforcement (unfairness) +- No automation (wasted time) +- Over-automation (losing human judgment) + +--- + +## Tools and Resources + +### GitHub CLI +- `gh`: Official GitHub CLI +- Create issues and PRs from terminal +- Review PRs locally +- Manage releases + +### Browser Extensions +- Refined GitHub: Enhanced UI +- OctoLinker: Navigate dependencies +- GitHub Dark Theme: Eye comfort +- Notifications Preview: Quick scanning + +### Third-Party Tools +- GitKraken: Visual Git client +- Fork: Git client +- SourceTree: Free Git GUI +- Git Tower: macOS/Windows client + +### Integration Platforms +- Zapier: Connect GitHub to other services +- IFTTT: Automation recipes +- Integromat: Advanced workflows + +--- + +## Further Reading + +- [GitHub Guides](https://guides.github.com/) +- [GitHub Skills](https://skills.github.com/) +- [GitHub Blog](https://github.blog/) +- [GitHub Changelog](https://github.blog/changelog/) +- [GitHub Community Forum](https://github.community/) diff --git a/docs/article-summaries/logging-best-practices.md b/docs/article-summaries/logging-best-practices.md new file mode 100644 index 0000000..dd870bd --- /dev/null +++ b/docs/article-summaries/logging-best-practices.md @@ -0,0 +1,90 @@ +# Logging Best Practices + +A collection of insights and best practices for logging in software applications. + +## Overview + +Effective logging is crucial for debugging, monitoring, and maintaining software systems. This document summarizes key learnings from various resources about logging best practices. + +--- + +## Log Levels: Rule of Thumb + +**Source:** [Stack Overflow - Logging levels logback rule of thumb](https://stackoverflow.com/questions/7839565/logging-levels-logback-rule-of-thumb-to-assign-log-levels/8021604#8021604) + +Practical guidelines for assigning logging levels: + +### ERROR +Log failures requiring human intervention. Apply the "2AM rule"—if an on-call person should be woken up, use ERROR. Examples: system failures, unhandled exceptions, critical dependency issues. + +### WARN +Document unexpected events that don't require immediate action but need attention. As one answer states: "an unexpected technical or business event happened, customers may be affected, but probably no immediate human intervention is required." + +### INFO +Record significant lifecycle and boundary events. Use for system startup/shutdown, user sessions, and important business transactions. Keep volume reasonable to remain useful in production. + +### DEBUG +Log detailed flow information helpful during development and QA. Include method entry/exit points and decision outcomes. This supports troubleshooting without production overhead. + +### TRACE +Reserve for extremely detailed, high-volume data you'd rarely enable. Examples include full object dumps or per-iteration loop logging—typically development-only. + +### Key Principle +The core distinction: logs should serve **production support and forensic analysis**. Include sufficient context (thread IDs, user info, specific details) to make messages actionable rather than merely informational. + +--- + +## Python Logging: Professional Practices + +**Source:** [How to Log in Python Like a Pro](https://guicommits.com/how-to-log-in-python-like-a-pro/) + +*Note: This article was not accessible during summarization. Key topics typically covered include:* +- Proper logger configuration and setup +- Structured logging approaches +- Integration with application frameworks +- Performance considerations +- Common pitfalls to avoid + +--- + +## What to Log and Avoiding Alert Fatigue + +**Source:** [What should you log in an application](https://cloudncode.blog/2016/12/30/what-should-you-log-in-an-application-and-how-to-avoid-having-24x7-support-looking-at-them/) + +*Note: This article was not accessible during summarization. Key topics typically covered include:* +- Identifying critical events worth logging +- Balancing information needs with log volume +- Preventing alert fatigue for support teams +- Log retention and rotation strategies +- Distinguishing between application and audit logs + +--- + +## Logging Levels: The Wrong Abstraction + +**Source:** [Logging levels: the wrong abstraction | IG Labs](https://labs.ig.com/logging-level-wrong-abstraction) + +*Note: This article was not accessible during summarization. This article typically discusses:* +- Why traditional log levels might be the wrong mental model +- Alternative approaches to categorizing logs +- Context-based logging strategies +- Moving beyond severity-based logging + +--- + +## General Best Practices Summary + +Based on the accessible resources, here are key takeaways: + +1. **Purpose-Driven Logging**: Always consider who will read the logs and for what purpose +2. **Actionable Information**: Include enough context to take action without guesswork +3. **Appropriate Levels**: Use the right log level based on required response, not perceived importance +4. **Production Readiness**: Design logging with production support in mind from the start +5. **Performance Awareness**: Balance information needs with application performance +6. **Consistent Context**: Include identifiers (user IDs, transaction IDs, thread IDs) consistently + +## Related Resources + +- Structured logging libraries for Python (structlog, python-json-logger) +- Log aggregation and analysis tools (ELK stack, Splunk, Datadog) +- Application monitoring and error tracking (Sentry, Rollbar, NewRelic) diff --git a/docs/article-summaries/python-best-practices.md b/docs/article-summaries/python-best-practices.md new file mode 100644 index 0000000..2dbbd14 --- /dev/null +++ b/docs/article-summaries/python-best-practices.md @@ -0,0 +1,574 @@ +# Python Best Practices + +A comprehensive guide to writing high-quality Python code, from style conventions to project structure. + +## Overview + +This document compiles Python-specific best practices covering code style, project organization, tooling, and modern development workflows. + +--- + +## Python Code Style Guide + +**Source:** [The Hitchhiker's Guide to Python - Style Guide](https://docs.python-guide.org/writing/style/) + +### Core Philosophy + +Python's design emphasizes readability and explicit code. The community follows established conventions to make code accessible and maintainable across projects. + +### General Principles + +**Explicit Over Implicit**: Code should clearly express intent. Use straightforward function signatures and direct return statements rather than relying on unpacking tricks or magic. + +**One Statement Per Line**: Avoid combining multiple operations on a single line, except for concise list comprehensions. This improves clarity and debugging. + +**Function Arguments**: Use positional arguments for essential parameters, keyword arguments with defaults for optional settings. Avoid `*args` and `**kwargs` unless truly necessary, as they reduce clarity about what the function accepts. + +**Avoiding Complexity**: Python offers powerful metaprogramming capabilities, but these should be used sparingly. Readability trumps cleverness—"A Pythonista knows how to kill with a single finger, and never to actually do it." + +**Responsibility Culture**: Python has no private keyword. Instead, the community uses underscore prefixes (`_variable`) to indicate internal implementation details that shouldn't be accessed directly. + +--- + +## Common Python Idioms + +### Unpacking +Assign tuple elements to variables efficiently: +```python +# Swapping variables +a, b = b, a + +# Multiple return values +def get_coordinates(): + return 10, 20 + +x, y = get_coordinates() +``` + +### Throwaway Variables +Use `_` for unused assignments: +```python +for _ in range(10): + print("Hello") + +# Unpacking with ignored values +first, *_, last = [1, 2, 3, 4, 5] +``` + +### String Operations +```python +# Joining strings (preferred) +result = ''.join(['hello', ' ', 'world']) + +# String formatting (modern) +name = "Alice" +greeting = f"Hello, {name}!" # f-strings (Python 3.6+) +``` + +### Collections +Use the right data structure: +```python +# Sets for membership testing +allowed_users = {'alice', 'bob', 'charlie'} +if user in allowed_users: # O(1) lookup + grant_access() + +# Dictionaries for key-value pairs +config = {'host': 'localhost', 'port': 8080} +``` + +--- + +## PEP 8 and Style Enforcement + +### PEP 8 Overview + +**PEP 8** is the official Python style guide. Key points: + +- **Indentation**: 4 spaces (not tabs) +- **Line Length**: Maximum 79 characters +- **Blank Lines**: 2 between top-level definitions, 1 between methods +- **Imports**: One per line, grouped (standard lib, third-party, local) +- **Naming Conventions**: + - `snake_case` for functions and variables + - `PascalCase` for classes + - `UPPER_CASE` for constants + - `_leading_underscore` for internal use + +### Style Checking Tools + +**pycodestyle** (formerly pep8): Checks compliance with PEP 8 +```bash +pycodestyle myfile.py +``` + +**autopep8**: Automatically fixes PEP 8 violations +```bash +autopep8 --in-place --aggressive myfile.py +``` + +**yapf**: Google's Python formatter +```bash +yapf --in-place myfile.py +``` + +**black**: Opinionated, uncompromising formatter +```bash +black myfile.py +``` + +--- + +## Pythonic Practices + +### Implicit Truthiness +```python +# Good +if items: + process(items) + +# Avoid +if items != []: + process(items) +``` + +### Dictionary Operations +```python +# Safe dictionary access +value = config.get('key', default_value) + +# Membership testing +if 'key' in config: + use(config['key']) + +# Dictionary comprehensions +squares = {x: x**2 for x in range(10)} +``` + +### List Comprehensions +```python +# Good +evens = [x for x in range(10) if x % 2 == 0] + +# Avoid nested loops in comprehensions (use nested for loops instead) +# Good +result = [] +for x in matrix: + for y in x: + result.append(y) +``` + +### Context Managers +```python +# Always use 'with' for file operations +with open('file.txt', 'r') as f: + content = f.read() + +# Multiple context managers +with open('input.txt') as infile, open('output.txt', 'w') as outfile: + outfile.write(infile.read()) +``` + +### Line Continuation +```python +# Use parentheses (preferred) +result = ( + some_function(arg1, arg2) + + another_function(arg3) +) + +# Avoid backslashes +result = some_function(arg1, arg2) \ + + another_function(arg3) # Not preferred +``` + +--- + +## Python Package Template + +**Source:** [Python Package Template by TezRomacH](https://github.com/TezRomacH/python-package-template) + +This cookiecutter template demonstrates modern Python development standards by integrating essential tools and workflows. + +### Development Tools + +The template leverages **code quality and formatting tools**: +- **Black**: Uncompromising code formatter +- **isort**: Import statement organizer +- **pyupgrade**: Automatic syntax upgrades to newer Python versions +- **MyPy**: Static type checking +- **Pytest**: Testing framework +- **Darglint**: Docstring validation +- **Safety**: Security vulnerability scanning +- **Bandit**: Security issue detection + +Pre-commit hooks automate these checks before commits, ensuring code meets standards before reaching the repository. + +### Project Structure + +**Poetry manages dependencies** through `pyproject.toml` and `setup.cfg`, supporting Python 3.7+. The template provides well-configured configuration files including `.editorconfig`, `.gitignore`, and `.dockerignore`. + +Typical structure: +``` +my_package/ +├── .github/ +│ └── workflows/ # CI/CD pipelines +├── docs/ # Documentation +├── my_package/ # Source code +│ ├── __init__.py +│ └── module.py +├── tests/ # Test files +│ ├── __init__.py +│ └── test_module.py +├── .editorconfig +├── .gitignore +├── .pre-commit-config.yaml +├── pyproject.toml # Project metadata and dependencies +├── setup.cfg # Tool configurations +├── README.md +├── LICENSE +└── CONTRIBUTING.md +``` + +### CI/CD & Automation + +GitHub Actions powers the build pipeline with predefined workflows. **"Automatic drafts of new releases with Release Drafter"** organize pull request changes by labels, following Semantic Versioning. + +The Stale bot automatically manages inactive issues, while Dependabot keeps dependencies current. + +### Community Standards + +The template auto-generates governance files: +- **LICENSE**: Project licensing +- **CONTRIBUTING.md**: Contribution guidelines +- **CODE_OF_CONDUCT.md**: Community standards +- **SECURITY.md**: Security policy + +Pull request and issue templates guide contributor interactions. + +### Deployment + +Docker support and Makefile automation streamline builds, testing, and deployment tasks. This comprehensive approach reduces setup friction while establishing professional development practices across new projects. + +--- + +## Modern Python Tooling + +### Dependency Management + +**Poetry** (Recommended for modern projects): +```bash +# Initialize new project +poetry new my-project + +# Add dependencies +poetry add requests + +# Add dev dependencies +poetry add --dev pytest + +# Install dependencies +poetry install + +# Run commands in virtual environment +poetry run python script.py +``` + +**pip** with **requirements.txt**: +```bash +# Install from requirements file +pip install -r requirements.txt + +# Generate requirements +pip freeze > requirements.txt +``` + +**pip-tools** for deterministic builds: +```bash +# requirements.in +requests +flask>=2.0 + +# Compile to requirements.txt +pip-compile requirements.in +``` + +### Type Checking + +**mypy** for static type analysis: +```python +# Type hints +def greet(name: str) -> str: + return f"Hello, {name}!" + +# Type checking collections +from typing import List, Dict, Optional + +def process_items(items: List[str]) -> Dict[str, int]: + return {item: len(item) for item in items} + +# Optional types +def find_user(user_id: int) -> Optional[User]: + return users.get(user_id) +``` + +### Linting + +**flake8** combines multiple tools: +```bash +flake8 my_package/ +``` + +**pylint** for comprehensive analysis: +```bash +pylint my_package/ +``` + +**ruff** - Fast Python linter (modern alternative): +```bash +ruff check my_package/ +``` + +### Testing + +**pytest** - Modern testing framework: +```python +# test_calculator.py +def test_addition(): + assert 1 + 1 == 2 + +def test_division(): + assert 10 / 2 == 5 + +# Fixtures +import pytest + +@pytest.fixture +def sample_data(): + return [1, 2, 3, 4, 5] + +def test_sum(sample_data): + assert sum(sample_data) == 15 +``` + +### Documentation + +**Sphinx** for documentation generation: +```bash +# Initialize Sphinx +sphinx-quickstart docs/ + +# Build documentation +cd docs/ +make html +``` + +**MkDocs** for Markdown-based docs: +```bash +# Install +pip install mkdocs + +# Create project +mkdocs new my-project + +# Serve locally +mkdocs serve + +# Build static site +mkdocs build +``` + +--- + +## Configuration Files + +### pyproject.toml + +Modern Python configuration standard (PEP 518): +```toml +[tool.poetry] +name = "my-package" +version = "0.1.0" +description = "A sample package" +authors = ["Your Name "] + +[tool.poetry.dependencies] +python = "^3.8" +requests = "^2.28.0" + +[tool.poetry.dev-dependencies] +pytest = "^7.0" +black = "^22.0" +mypy = "^0.950" + +[tool.black] +line-length = 100 +target-version = ['py38'] + +[tool.isort] +profile = "black" +line_length = 100 + +[tool.mypy] +python_version = "3.8" +warn_return_any = true +warn_unused_configs = true +``` + +### setup.cfg + +Traditional configuration file: +```ini +[flake8] +max-line-length = 100 +exclude = .git,__pycache__,build,dist + +[mypy] +python_version = 3.8 +warn_return_any = True +warn_unused_configs = True + +[tool:pytest] +testpaths = tests +python_files = test_*.py +python_classes = Test* +python_functions = test_* +``` + +### .pre-commit-config.yaml + +Automate checks before commits: +```yaml +repos: + - repo: https://github.com/psf/black + rev: 22.10.0 + hooks: + - id: black + language_version: python3.8 + + - repo: https://github.com/pycqa/isort + rev: 5.10.1 + hooks: + - id: isort + + - repo: https://github.com/pycqa/flake8 + rev: 5.0.4 + hooks: + - id: flake8 + + - repo: https://github.com/pre-commit/mirrors-mypy + rev: v0.990 + hooks: + - id: mypy +``` + +--- + +## Best Practices Summary + +### Code Quality +1. **Follow PEP 8**: Use automated formatters like Black +2. **Type Hints**: Add type annotations for better IDE support and error detection +3. **Docstrings**: Document all public functions, classes, and modules +4. **Keep it Simple**: Prefer readability over cleverness +5. **DRY Principle**: Don't Repeat Yourself + +### Project Structure +1. **Logical Organization**: Group related functionality +2. **Clear Naming**: Use descriptive names for modules and packages +3. **Separation of Concerns**: Keep business logic separate from infrastructure +4. **Configuration Files**: Use modern tools like pyproject.toml +5. **Tests Alongside Code**: Mirror source structure in tests + +### Development Workflow +1. **Virtual Environments**: Always use isolated environments +2. **Version Control**: Commit early and often +3. **Pre-commit Hooks**: Catch issues before they reach the repository +4. **Continuous Integration**: Run tests on every commit +5. **Dependency Pinning**: Lock dependency versions for reproducibility + +### Documentation +1. **README First**: Write documentation as you code +2. **API Documentation**: Use docstrings for automatic generation +3. **Examples**: Include usage examples +4. **Changelog**: Maintain a history of changes +5. **Type Hints**: They serve as inline documentation + +### Security +1. **Dependency Scanning**: Use tools like Safety and Bandit +2. **Secret Management**: Never commit credentials +3. **Input Validation**: Validate and sanitize all inputs +4. **Regular Updates**: Keep dependencies current +5. **Security Policies**: Document vulnerability reporting process + +--- + +## Common Anti-Patterns to Avoid + +### Code Smells +- **God Classes**: Classes that do too much +- **Long Functions**: Functions exceeding 20-30 lines +- **Deep Nesting**: More than 3-4 levels of indentation +- **Magic Numbers**: Unexplained constants in code +- **Mutable Defaults**: Using mutable objects as default arguments + +### Bad Practices +```python +# DON'T: Mutable default arguments +def add_item(item, items=[]): # Bug: list is shared across calls + items.append(item) + return items + +# DO: Use None as default +def add_item(item, items=None): + if items is None: + items = [] + items.append(item) + return items + +# DON'T: Bare except +try: + risky_operation() +except: # Catches everything, including KeyboardInterrupt + pass + +# DO: Catch specific exceptions +try: + risky_operation() +except ValueError as e: + log.error(f"Invalid value: {e}") + +# DON'T: String concatenation in loops +result = "" +for item in items: + result += str(item) # Creates new string each iteration + +# DO: Use join +result = "".join(str(item) for item in items) +``` + +--- + +## Resources and Further Reading + +### Official Documentation +- [Python Documentation](https://docs.python.org/) +- [PEP 8 Style Guide](https://pep8.org/) +- [The Python Tutorial](https://docs.python.org/3/tutorial/) + +### Books +- "Fluent Python" by Luciano Ramalho +- "Effective Python" by Brett Slatkin +- "Python Tricks" by Dan Bader + +### Online Resources +- [Real Python](https://realpython.com/) +- [Python Package Index (PyPI)](https://pypi.org/) +- [Awesome Python](https://github.com/vinta/awesome-python) + +### Tools +- [Black](https://black.readthedocs.io/) +- [Poetry](https://python-poetry.org/) +- [pytest](https://docs.pytest.org/) +- [mypy](http://mypy-lang.org/) +- [Sphinx](https://www.sphinx-doc.org/) diff --git a/docs/article-summaries/readme-best-practices.md b/docs/article-summaries/readme-best-practices.md new file mode 100644 index 0000000..8719133 --- /dev/null +++ b/docs/article-summaries/readme-best-practices.md @@ -0,0 +1,341 @@ +# README Best Practices + +A comprehensive guide to creating effective README files for software projects. + +## Overview + +A README is often the first thing people see when encountering your project. This document compiles best practices from multiple sources on creating READMEs that are informative, welcoming, and useful. + +--- + +## README Checklist + +**Source:** [README Review - Lars Wirzenius](https://liw.fi/readme-review/) + +According to Lars Wirzenius, a good README should include these elements: + +### Core Purpose +"A README is meant for someone who is first encountering the project to be able to quickly decide if they want to learn more" about it. + +### Essential Components + +1. **Blurb** - A concise, information-dense overview for newcomers unfamiliar with the topic + +2. **Usage Example** - Demonstration of typical software usage, particularly when it aids comprehension + +3. **Legal Information** - Clear statements regarding copyright and applicable open source licenses + +4. **Optional But Helpful Elements:** + - Installation instructions + - Test suite execution guidance + - References to additional documentation + - Links to project information + - Contributor details + +### What It's NOT +The README serves as an introduction, not a comprehensive manual. Detailed documentation can exist separately with appropriate cross-references. + +Wirzenius emphasizes that a README functions as a filtering tool—helping potential users quickly assess project relevance before deeper engagement. The document should be self-contained enough to stand independently without requiring external context. + +--- + +## Make a README + +**Source:** [Make a README](https://www.makeareadme.com/) + +### What & Why + +A README is a text file introducing your project. It answers common questions about installation, usage, and collaboration—essential for any programming project you want others to use or contribute to. + +### Essential Sections + +The guide recommends including: + +- **Name**: A self-explanatory project title +- **Description**: What the project does with relevant context +- **Installation**: Step-by-step setup instructions, considering novice users +- **Usage**: Practical examples with expected outputs +- **Contributing**: Guidelines for potential collaborators +- **License**: Legal terms for open source projects + +Additional valuable sections include badges, visuals (screenshots/GIFs), support channels, roadmap, and project status. + +### Best Practices + +**Timing & Placement**: Create your README before sharing publicly, preferably as your first file. Place it in the top-level directory where code hosting platforms automatically display it. + +**Format**: Markdown is the standard, offering lightweight formatting. Most editors and platforms support it well. + +**Length Philosophy**: As the guide states, "too long is better than too short." Consider supplementary documentation (wikis, dedicated sites) rather than omitting information. + +**Quality Assurance**: Include commands for linting and running tests to ensure code quality and prevent breaking changes. + +--- + +## Software Release Practice HOWTO - README Section + +**Source:** [Software Release Practice HOWTO](https://tldp.org/HOWTO/Software-Release-Practice-HOWTO/distpractice.html#readme) + +*Note: This article was not accessible during summarization. Common themes from software release practice guides:* + +### Distribution Best Practices +- **README**: Project overview and quick start +- **INSTALL**: Detailed installation instructions +- **CHANGELOG**: Version history and changes +- **LICENSE**: Legal terms +- **CONTRIBUTING**: How to contribute +- **AUTHORS**: Credits and acknowledgments + +### README Specific Content +- One-paragraph project description +- Requirements and dependencies +- Quick installation summary +- Basic usage examples +- Links to full documentation +- Contact information or issue reporting + +--- + +## Awesome README + +**Source:** [Awesome README](https://github.com/matiassingers/awesome-readme) + +Based on the curated examples, outstanding README files consistently incorporate these elements: + +### Visual Elements +Project logos, screenshots, and animated GIFs demonstrating functionality are nearly universal. These provide immediate visual context before readers engage with text. + +### Clear Structure +A table of contents enables easy navigation. Logical sections typically include project description, installation instructions, usage examples, and contribution guidelines. + +### Informative Badges +Status indicators for build health, version numbers, and test coverage appear throughout excellent examples, offering at-a-glance project health metrics. + +### Comprehensive Documentation +Strong READMEs explain not just *what* a project does, but *why* it exists. This includes philosophy notes, design decisions, and architectural context. + +### Accessibility Features +Multiple examples emphasize inclusive language, step-by-step instructions with screenshots, and support for diverse learning styles. One standout note: "friendly, inclusive tone and accessible setup instructions" help newcomers contribute. + +### Contributor Recognition +Displaying contributor avatars and acknowledgment sections builds community investment. + +### Architecture Documentation +Dedicated ARCHITECTURE.md files or sections help developers understand codebase organization through diagrams, source maps, and invariant descriptions. + +### Interactive Elements +Live demos, playground links, and collapsible sections reduce cognitive load while maintaining comprehensive documentation. + +The strongest READMEs treat documentation as essential project work, not an afterthought. + +--- + +## Best README Template + +**Source:** [Best README Template](https://github.com/othneildrew/Best-README-Template) + +*Note: This is a template repository. Common elements from popular README templates:* + +### Template Sections +1. **Project Logo/Banner** +2. **Title and Tagline** +3. **Shields/Badges** (build status, version, license, etc.) +4. **About the Project** + - Screenshots + - Built With (tech stack) +5. **Getting Started** + - Prerequisites + - Installation +6. **Usage** + - Examples + - Code snippets +7. **Roadmap** +8. **Contributing** +9. **License** +10. **Contact** +11. **Acknowledgments** + +### Template Benefits +- Consistent structure across projects +- Don't forget important sections +- Professional appearance +- Easy to customize +- Saves time on new projects + +--- + +## Comprehensive README Best Practices + +Based on all sources, here's a synthesis of README best practices: + +### Must-Have Sections +1. **Project Name and Description** + - Clear, concise title + - One-paragraph overview + - Why this project exists + +2. **Installation** + - Prerequisites listed explicitly + - Step-by-step instructions + - Platform-specific notes if applicable + - Dependency installation commands + +3. **Usage** + - Basic examples with expected output + - Common use cases + - Code snippets + - Screenshots or GIFs for visual tools + +4. **License** + - Clear license information + - Link to full LICENSE file + +### Should-Have Sections +5. **Contributing** + - How to report bugs + - How to suggest features + - How to submit pull requests + - Code of conduct link + +6. **Documentation** + - Link to full docs if they exist + - API reference if applicable + - Architecture overview for complex projects + +7. **Support** + - Where to get help + - Issue tracker link + - Contact information or community channels + +### Nice-to-Have Sections +8. **Badges** + - Build status + - Coverage + - Version + - License + - Download count + +9. **Table of Contents** + - For longer READMEs + - Enables quick navigation + +10. **Changelog** + - Or link to CHANGELOG.md + - Recent notable changes + +11. **Authors/Contributors** + - Credit those who contributed + - Links to profiles + +12. **Acknowledgments** + - Libraries used + - Inspiration sources + - Related projects + +13. **Roadmap** + - Planned features + - Known issues + - Future direction + +### Writing Style Guidelines + +**Be Concise but Complete** +- Get to the point quickly +- Don't assume prior knowledge +- Define domain-specific terms +- Use simple language + +**Be Welcoming** +- Use inclusive language +- Encourage contributions +- Assume good intentions +- Lower barriers to entry + +**Be Practical** +- Provide working examples +- Include actual commands to run +- Show expected output +- Test all instructions + +**Be Visual** +- Use screenshots for UI +- Use diagrams for architecture +- Use GIFs for workflows +- Use code blocks with syntax highlighting + +### Format and Structure + +**Markdown Best Practices** +- Use headings hierarchically (h1, h2, h3) +- Use code blocks with language specification +- Use lists for scannable information +- Use tables for structured data +- Use links instead of raw URLs + +**File Organization** +- README.md in repository root +- Additional docs in `/docs` directory +- Keep README focused on getting started +- Link to detailed docs for complex topics + +### Common Mistakes to Avoid + +1. **No README at all** +2. **Generic boilerplate left unchanged** +3. **Outdated installation instructions** +4. **No usage examples** +5. **Broken links or images** +6. **Assuming too much knowledge** +7. **Writing a novel** (save details for docs) +8. **No license information** +9. **No contribution guidelines** +10. **Forgetting to update** after major changes + +### README Maintenance + +- **Update with releases**: Keep installation instructions current +- **Test regularly**: Verify all commands and links work +- **Accept feedback**: Users will tell you what's missing +- **Version if needed**: Major changes might need versioned docs +- **Translate if global**: Consider multiple language versions + +### Tools and Resources + +**Generators** +- [readme.so](https://readme.so/) - Visual README editor +- [Make a README](https://www.makeareadme.com/) - Guide and generator +- [Standard Readme](https://github.com/RichardLitt/standard-readme) - Specification + +**Templates** +- [Best README Template](https://github.com/othneildrew/Best-README-Template) +- [Awesome README](https://github.com/matiassingers/awesome-readme) +- Language/framework-specific templates + +**Badges** +- [Shields.io](https://shields.io/) - Badge generation +- [Badgen](https://badgen.net/) - Fast badge service + +**Screenshot Tools** +- [Carbon](https://carbon.now.sh/) - Beautiful code screenshots +- [Screely](https://www.screely.com/) - Generate browser mockups +- [LICEcap](https://www.cockos.com/licecap/) - Simple GIF capture + +## Examples of Excellent READMEs + +Some projects known for great documentation: +- [freeCodeCamp](https://github.com/freeCodeCamp/freeCodeCamp) +- [Node.js Best Practices](https://github.com/goldbergyoni/nodebestpractices) +- [Vue.js](https://github.com/vuejs/vue) +- [Electron](https://github.com/electron/electron) +- [TensorFlow](https://github.com/tensorflow/tensorflow) + +## Conclusion + +A great README: +- **Welcomes** newcomers warmly +- **Informs** quickly and clearly +- **Guides** through setup and usage +- **Invites** contribution +- **Maintains** accuracy over time + +Remember: Your README is often the first impression of your project. Make it count! diff --git a/docs/article-summaries/testing-best-practices.md b/docs/article-summaries/testing-best-practices.md new file mode 100644 index 0000000..e01750b --- /dev/null +++ b/docs/article-summaries/testing-best-practices.md @@ -0,0 +1,159 @@ +# Testing Best Practices + +A collection of testing strategies and best practices for software development. + +## Overview + +This document compiles insights on effective testing strategies, including test design, mocking approaches, and practical testing philosophies. + +--- + +## Python Testing Style Guide + +**Source:** [My Python Testing Style Guide](https://blog.thea.codes/my-python-testing-style-guide/) + +Stargirl Flowers' testing philosophy emphasizes pragmatism over dogmatism, focusing on behavior rather than implementation details. + +### Key Principles + +#### Test Organization & Naming +Follow pytest conventions with files named `test_*.py`. Match test names to their targets, adding descriptive suffixes for different scenarios (e.g., `test_refresh_failure`). + +#### Assert Outcomes, Not Steps +Tests should verify the final state rather than method invocations. As the guide notes, "Your assertions should test that the state of the world matches the outcome you expected." + +#### Prefer Real Objects +Use actual collaborators whenever feasible. This catches bugs and encourages cleaner code design. Mock objects should be reserved for situations where real implementations aren't practical. + +#### Strict Mock Specifications +When mocking is necessary, always use `mock.create_autospec()` or `mock.patch(autospec=True)`. This ensures your tests break when interfaces change, preventing hidden bugs in production code. + +#### Consider Alternatives to Mocks +Stubs (objects with canned responses) and fakes (simplified working implementations) often provide better test clarity than complex mocks. + +#### Naming Convention +Name mocks identically to real collaborators—avoid prefixes like `mock_` or `fake_`. This reinforces treating them as genuine substitutes. + +#### Fixture Usage +Use fixtures sparingly, preferring factory helpers for setup. Reserve fixtures for complex setup/teardown logic or dependency injection scenarios. + +--- + +## Stubbing vs. Mocking + +**Source:** [Outside-In Testing Concepts - Stubbing and Mocking](https://outsidein.dev/testing-concepts.html#stubbing-and-mocking) + +*Note: This article was not accessible during summarization. Key concepts typically covered include:* + +### Stubs +- Return predetermined responses to method calls +- Used to provide indirect inputs to the system under test +- Don't verify how they were called +- Simpler and more stable than mocks + +### Mocks +- Verify that specific methods were called with specific parameters +- Used to verify indirect outputs from the system under test +- More brittle but useful for testing side effects +- Require careful maintenance as code evolves + +### When to Use Each +- **Use stubs** when you need to control inputs to your test subject +- **Use mocks** when you need to verify that your code called something correctly +- **Prefer real objects** when practical for more reliable tests + +--- + +## Testing the Diff + +**Source:** [Testing the Diff - Vinta Blog](https://www.vinta.com.br/blog/2021/testing-the-diff/) + +*Note: This article was not accessible during summarization. This concept typically covers:* + +### Core Concept +Instead of running the entire test suite on every change, focus testing efforts on: +- Code that was modified +- Code that depends on the modified code +- Integration points affected by changes + +### Benefits +- Faster feedback loops during development +- More efficient use of CI/CD resources +- Encourages smaller, focused commits +- Reduces testing fatigue + +### Implementation Strategies +- Use coverage tools to identify affected tests +- Implement test impact analysis +- Tag tests by feature area or component +- Use git diff to identify changed files and related tests + +### Considerations +- Still run full test suite before merging/releasing +- Ensure dependency graphs are accurate +- Balance speed with comprehensive coverage +- Consider integration test implications + +--- + +## General Testing Best Practices Summary + +Based on the accessible resources and industry standards: + +### Test Design +1. **Focus on Behavior**: Test what the code does, not how it does it +2. **One Assertion Concept per Test**: Tests should verify a single logical outcome +3. **Descriptive Names**: Test names should explain what's being tested and expected outcome +4. **Arrange-Act-Assert Pattern**: Structure tests clearly with setup, execution, and verification + +### Mock Strategy +1. **Prefer Real Objects**: Use actual implementations when practical +2. **Strict Specifications**: Always use autospec for mocks +3. **Minimize Mocking**: Too many mocks indicate poor design +4. **Test Behavior, Not Implementation**: Don't verify internal method calls unless they're the feature + +### Test Organization +1. **Mirror Source Structure**: Test files should match source code organization +2. **Shared Fixtures**: Use factory functions for common test data +3. **Isolated Tests**: Each test should be independent and runnable in any order +4. **Clear Setup/Teardown**: Make test prerequisites explicit + +### Efficiency +1. **Fast Tests**: Keep unit tests fast (< 100ms each) +2. **Parallel Execution**: Design tests to run concurrently +3. **Strategic Coverage**: Focus on critical paths and edge cases +4. **Test Pyramid**: Many unit tests, fewer integration tests, minimal E2E tests + +### Maintenance +1. **Refactor Tests**: Treat test code with the same care as production code +2. **Delete Obsolete Tests**: Remove tests for removed features +3. **Update with Refactoring**: Keep tests aligned with code changes +4. **Document Complex Tests**: Explain why a test exists if non-obvious + +## Related Tools & Frameworks + +### Python Testing +- **pytest**: Modern, feature-rich testing framework +- **unittest**: Standard library testing framework +- **hypothesis**: Property-based testing +- **pytest-cov**: Coverage reporting +- **pytest-xdist**: Parallel test execution + +### Mocking & Stubbing +- **unittest.mock**: Standard library mocking +- **pytest-mock**: pytest integration for mocking +- **responses**: Mock HTTP requests +- **freezegun**: Mock datetime + +### Coverage & Analysis +- **coverage.py**: Code coverage measurement +- **pytest-cov**: pytest coverage plugin +- **mutation testing**: Tools like mutmut to test test quality + +## Further Reading + +- Test-Driven Development (TDD) principles +- Behavior-Driven Development (BDD) approaches +- Property-based testing with Hypothesis +- Integration testing strategies +- End-to-end testing best practices