So, here's part of a totally subjective, non-comprehensive list of frustrations and "best practices" I've been collecting. Some are based on personal experience and others are ideals from the node community that I'm trying to incorporate.
I'm looking for more tips like this. Please share your knowledge or vent your frustrations here. *Stream-like apis* If your code is emitting data/error events but not inheriting from Stream, your module becomes inoperable with other streams, e.g. can't pipe(). This severely reduces your module's flexibility. *Inconsistent sync/async* When functions are sometimes sync and sometimes async lead to hard to use apis, subtle bugs and more error handling wrapper code. Always wrap callbacks in process.nextTick if they're not behind an async operation. Simple. *Prematurely optimising* e.g. choosing to avoid readable, semantic iteration with Array#map/forEach/reduce/filter… instead using for loops 'because they're faster'. Unless you're writing a database driver or something similar, focus on writing maintainable, clean code. Optimising your io and designing to scale horizontally rather than tuning individual code paths will reap far more benefit and is more inline with node's focus (io bound tasks over cpu bound tasks). *OO is an implementation detail* Rather than exporting constructors as the primary API of a module, just give me a factory method please. *Fear of dependencies* Some developers exhibit a reluctance to use modules due to the 'overheads' of managing dependencies, which is probably a stigma carried from other non-nodejs environments. It's not nearly as big of an issue in node, so don't hesitate to `npm install` with reckless abandon. *Duplication of effort* Creating new modules instead of improving existing modules dilutes the quality of the module ecosystem. Diversity is great, but only when there’s a meaningful reason for that diversity to exist. "All the other modules for X were broken or buggy", sounds like a good reason to start a new module, but perhaps you're throwing baby out with bathwater… the fix may have been a simple task but instead of 5 functionally similar, sparingly maintained modules, we’ve now got 6, and more surface area for bugs. Nice work. Another reason new modules are created is because the consumer didn't appreciate the module's api; this is a trickier issue as people love bikeshedding over this kind of stuff. I've found it's often easiest to just wrap modules with an api you prefer rather than starting from scratch or arguing with the author. *Learn to npm* npm contains a great amount of functionality and information that many people don't seem to know about. For example you should rarely have need to edit your package.json (especially when installing/updating modules) as npm has commands to create <https://npmjs.org/doc/init.html> and update<https://npmjs.org/doc/install.html> your package.json for you. 'npm help' is an excellent source of answers to many questions. There's plenty to learn about npm<http://www.devthought.com/2012/02/17/npm-tricks/>, please share any tricks. *npm scripts vs readme *If you encapsulate all the knowledge about how to build/boot/test your app into your package.json scripts <https://npmjs.org/doc/scripts.html>, that's less information you need to put into the readme and keeps things consistent. For example, if you setup a test script, I only need to know to run `npm test`, rather than hope you've included information about how to run your tests. If you change your test tool, or change the arguments, I don't even need to know since that information is embedded in the package.json. *Tagging releases* If you don't tag releases, it's a pain to find the commit that corresponds to a release. Use npm version <https://npmjs.org/doc/version.html> to generate tags. *Deep abstractions* Having many layers and long breadcrumb trails makes understanding and debugging your module difficult, raising the barrier to participation (and maintainability). Complexity is often presented as 'architecture'. Simplicity is key. <http://www.infoq.com/presentations/Simple-Made-Easy>If your system is becoming complicated, it's probably doing too much or you're going about it in the wrong way. *Refrain from building/using all-in-one frameworks** *This is not in keeping with the nodejs aesthetic<http://substack.net/posts/b96642/the-node-js-aesthetic>. Node isn't Rails. Having code coupled to a framework creates duplication of work, fragmentation and interoperability. This is bad. The trend towards modularisation is one of the best things node has got going for it over other environments, don't ruin it by creating silos. *MVC* Usually overkill. If your app is modular enough, you likely won't need much/any of it. MVC everywhere makes it more difficult to isolate features and break them into decoupled components, as well as encouraging some utterly ridiculous solutions (when all you have is a hammer…). Frameworks that dictate application architecture should be avoided as architecture should be determined by the problem at hand<http://blog.8thlight.com/uncle-bob/2011/09/30/Screaming-Architecture.html> not a framework. Moving away from MVC everywhere also gives you the ability to experiment with different patterns and evolve your architecture toolset. You'll be surprised at how simple some problems are if you don't contort everything to fit into the MVC mould. *Supply usage examples in modules* Most of TJ's and Substack's modules include working examples demonstrating various use cases. Showing how to use the module is far, far more important than narratives and lengthy api documentation in a readme. Code is a concrete explanation and usually uses less words (if not perhaps your code needs refactoring). *Supply usage examples upfront in readmes* Please put a usage example at the top of your readme. *Write tests* Tests help other developers have confidence they haven't accidentally broken anything when contributing to your project. Tests can also serve as usage examples in lieu of comprehensive examples/documentation. What else? Teach me of your ways. This part of some research for a presentation <http://jscamp.asia/> I'm putting together on a similar topic. -- Job Board: http://jobs.nodejs.org/ Posting guidelines: https://github.com/joyent/node/wiki/Mailing-List-Posting-Guidelines You received this message because you are subscribed to the Google Groups "nodejs" group. To post to this group, send email to nodejs@googlegroups.com To unsubscribe from this group, send email to nodejs+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/nodejs?hl=en?hl=en
