Let's Write Better Node Modules
2 likes4,529 views
The document discusses best practices for building effective Node.js modules, emphasizing the importance of accurate documentation, well-designed APIs, and thorough testing. Key components include creating effective readme files, providing clear API documentation, and designing for asynchronous usage and streams. It also highlights the need for semantic versioning and testing automation to maintain quality in Node.js module development.
Let's Write Better Node Modules
- 1. LET’S BUILD BETTER NODE MODULES NODE SUMMIT DECEMBER 2013 Copyright © twilio Inc. 2013
- 2. HI. I’M KEVIN. developer evangelist @ twilio
- 3. What is twilio? twilio makes it easy for developers to integrate voice calling and messaging into web and native mobile applications
- 5. “The goal is to have lots of user-created modules, that are all single-purpose and focused...so you can iterate get the best experience possible...”
- 8. 49,000 PACKAGES PyPI: ~37K | RubyGems: ~67K | NuGet: ~18K
- 10. Downloads in millions for October request optimist connect lodash 0 0.35 0.7 1.05 1.4 USERLAND CARRIES A HEAVY LOAD
- 11. IF USERLAND SUCKS, NODE SUCKS.
- 12. HOW WE CAN HELP • Provide accurate documentation optimized for how people read on the internet (scanning and searching) • Design idiomatic APIs that optimize for the job your module will be hired to do • Implement test automation and basic release management
- 13. DOCUMENTATION
- 14. DOCUMENT ALL THE THINGS • Very few userland modules have effective docs - common open source problem • Every module has different documentation needs • Great resource: Kevin Burke’s talk on this subject • Two most important components for node modules: • README (quick start) • API Docs
- 15. AN EFFECTIVE README • Focus on the job your module will be “hired” to do • Get user to success ASAP by staying focused: • What job does your module do? • How do you install/configure it? • ~3 examples of how to do the thing your module would be hired to do • Link to API docs and deeper info sources
- 16. CASE STUDIES • Mongoose: https://npmjs.org/package/mongoose • jsdom: https://npmjs.org/package/jsdom • browserify: https://npmjs.org/package/browserify • request: https://npmjs.org/package/request • node-uuid: https://npmjs.org/package/node-uuid
- 17. EFFECTIVE API DOCS • Describe the complete surface area of the API • Provide context for how the API is meant to be used • Make content readable and scannable • Provide complete and correct examples, but do not rely on them as API documentation • “Read the tests” is a cop out (see above)
- 18. DESCRIBING A NODE.JS API • Document all properties and functions from module.exports (harder than it sounds) • Document all function signatures • Function docs should ideally have: • Return value/type • Argument types • Example usage
- 19. PROVIDING CONTEXT • Show how your code is intended to be used • Demonstrate how it interconnects with other modules/platform features • Describe high-level use cases and concepts unique to your module
- 20. MAKE CONTENT READABLE • Users don’t read docs word for word - they scan in an F shape, looking for relevant bits • Include a table of contents for longer content (https://github.com/ thlorenz/doctoc) • Make the first 3-5 words of every line contain the most information possible • Use headers/images/code to break up scary blocks of text • Limit text on a page to columns of ~80 characters
- 21. PROVIDE EXAMPLES • Reinforce written docs with sample code that shows actual usage • Ideally, examples should be copy/cut/paste ready - include any necessary setup/teardown, including the “require” • Accuracy is key - broken examples are super frustrating
- 22. CASE STUDIES • Mongoose: http://mongoosejs.com/index.html • express: http://expressjs.com/api.html • browserify: https://github.com/substack/node-browserify • request: https://github.com/mikeal/request • node-uuid: https://npmjs.org/package/node-uuid
- 23. API DESIGN
- 24. NODE.JS MODULE API DESIGN • Check out: https://www.youtube.com/watch?v=aAb7hSCtvGw • Design for async usage • Use streams for I/O • Be mindful of the job your module has been hired to do
- 25. DESIGNING FOR ASYNC • Do not release Zalgo • Node core modules use a specific type of signature for async APIs that require callbacks • Function takes whatever arguments, and a callback • Callback is called with any error received as the first argument, formatted data is the second. • Sometimes there’s a third arg with a “raw” value in userland
- 26. DESIGN FOR STREAMS • If you do any sort of I/O, you’d do well to make your interface speak streams • Your API will interoperate well with the rest of the node ecosystem if you work with readable and writable streams • “When you grok streams, you grok node” - Isaac paraphrase
- 27. BE MINDFUL OF YOUR PURPOSE • Your module might do a few different things, but it probably has a few 80% use cases • Your API should be designed to do those jobs as quickly and efficiently as possible, with sensible default behavior
- 28. CASE STUDIES • browserify: https://github.com/substack/node-browserify • request: https://github.com/mikeal/request • twilio: http://twilio.github.io/twilio-node
- 30. MANAGING YOUR PROJECT • Ensure quality with testing and test automation (which can be super easy) • Ensure sanity with your module releases by using semantic versioning
- 31. MANAGING YOUR PROJECT • Promote quality with testing and test automation (which can be super easy) • Ensure sanity with your module releases by using semantic versioning
- 32. TESTING/AUTOMATION • Lots of great test frameworks, pick your favorite or just use assert • Do support “npm test” • Travis CI is your friend, and super easy to set up
- 33. RELEASE MANAGEMENT • If you follow semantic versioning, you’re probably doing fine • If an API breaks from 1.4 to 1.5, that’s a Very Bad Thing • Use git tags that match your npm versions • Doing the above makes release notes/change log very easy
- 34. CASE STUDIES • twilio: http://twilio.github.io/twilio-node
- 35. WRAPPING UP • You probably don’t get paid to write and share your module - thank you for contributing! • node.js relies on userland modules more than any other major server-side platform • If we care about the node ecosystem and community, we all have to step up with the quality of our contributions