My team often discusses how to present code samples effectively. We want to strike a balance between providing helpful, runnable (and fun!) examples and avoiding repetitive yet more secure boilerplate code.
Should you include comprehensive security and reliability features (like rate limiting or observability) in samples, even when those aren't the primary focus?
Another example of this is whether to use frameworks like Express and libraries like express-rate-limit. These can streamline implementation, but also potentially add complexity.
Why does this matter?
- Security Omitting safeguards like rate-limiting may cause issues for folks who copy pasta these samples straight into use. (Check out this OWASP resource on Denial of Services to understand why you'd want to have rate limiting as an example.)
- Maintainability Repeating these code blocks creates maintenance overhead.
- Clarity Focusing on the core concept improves readability.
I'd love to hear from others on this topic and hopefully spark up some conversations around common methodologies we could approach this as a community.
- How do you approach demonstrating concepts in code samples with regards to completeness and security?
- What are your preferred ways to manage common concerns like authentication and rate-limiting in a way that promotes reusability?
- How do you balance the use of frameworks/libraries with the goal of keeping samples clear and focused?
- What strategies do you employ to ensure consistency in code standards across your teams?
Top comments (0)