Your SlideShare is downloading. ×
Let's Write Better Node Modules
Upcoming SlideShare
Loading in...5
×

Thanks for flagging this SlideShare!

Oops! An error has occurred.

×
Saving this for later? Get the SlideShare app to save on your phone or tablet. Read anywhere, anytime – even offline.
Text the download link to your phone
Standard text messaging rates apply

Let's Write Better Node Modules

3,829
views

Published on

Talk for Node Summit 2013 - some guidelines for publishing node modules that move the community forward

Talk for Node Summit 2013 - some guidelines for publishing node modules that move the community forward

Published in: Technology

0 Comments
1 Like
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total Views
3,829
On Slideshare
0
From Embeds
0
Number of Embeds
0
Actions
Shares
0
Downloads
8
Comments
0
Likes
1
Embeds 0
No embeds

Report content
Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
No notes for slide

Transcript

  • 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
  • 4. “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...”
  • 5. https://scalenpm.org
  • 6. 49,000 PACKAGES PyPI: ~37K | RubyGems: ~67K | NuGet: ~18K
  • 7. 6,000,000+ DOWNLOADS PER DAY
  • 8. Downloads in millions for October request optimist connect lodash 0 0.35 0.7 1.05 1.4 USERLAND CARRIES A HEAVY LOAD
  • 9. IF USERLAND SUCKS, NODE SUCKS.
  • 10. 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
  • 11. DOCUMENTATION
  • 12. 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
  • 13. 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
  • 14. 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
  • 15. 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)
  • 16. 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
  • 17. 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
  • 18. 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
  • 19. 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
  • 20. 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
  • 21. API DESIGN
  • 22. 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
  • 23. 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
  • 24. 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
  • 25. 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
  • 26. CASE STUDIES • browserify: https://github.com/substack/node-browserify • request: https://github.com/mikeal/request • twilio: http://twilio.github.io/twilio-node
  • 27. TESTING AND RELEASES
  • 28. 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
  • 29. 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
  • 30. 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
  • 31. 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
  • 32. CASE STUDIES • twilio: http://twilio.github.io/twilio-node
  • 33. 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
  • 34. THANK YOU! @kevinwhinnery kw@twilio.com http://github.com/kwhinnery http://slideshare.net/kwhinnery