A friend of mine, Ken Sipe, once said (regarding statically typed languages and compile-time error checking) that compiling is very much like running an initial set of tests (that the compiler created instead of the developer).
Taking that idea one step forward, it is certainly good to create a document which describes the interface and how it is used (with examples) or ... However, Ken also said that tests are like executable intent, meaning you describe what should happen, and then you can also execute it to verify that it does. So one might simply *create a set of tests that test out the required functionality of your desired interface*, then use that to verify any objects that are supposed to be implementations (much like a compile check). This is also great if you are having someone else build the actual code, once they are done, run the tests against it and if it passes then it is implemented correctly. If your tests are written in a very readable way, then you might not even need much other documentation to accompany it, it already has examples of how to use, and if the tests describe the functionality then it can be fairly easy to read. It's probably good to have a good readme as well, but for somethings the tests might be sufficient. On Wednesday, 4 July 2012 02:15:56 UTC-5, Dave Horton wrote: > > Thanks much for the responses. As a server side guy new to node, I have > been trying to weigh in my own head whether some of the things I naturally > look around for are better viewed as opportunities to change my thinking to > do things in a new, and possibly more effective, way. (And, no doubt, > there is much that I see in the node ecosphere that is quite excitingly > better). In the case of interfaces, though, I do find myself missing the > ability to have a java-style kind of way of defining an interface. The > thing I like about java interfaces is that if I design an interface, and > someone tries to implement to it their code will break early - at compile > time -- if they don't get the API right (actually, their editor will > probably just add stubs of the necessary methods for them so they get it > right without much researching) . Surfacing those types of issues early is > a good thing, regardless of language. > > In node, I see a lot of nice documentation written by folks to describe > their APIs, which is nice, but on the other hand that type of docs seems > much more necessary than in other language. I also wonder if the lack of > interface constructs (or, altneratively, the 100 different ways you could > roll your own in JS, which seems true of most things) affects how people > write their code. For instance, I see lots of examples where people expose > objects in their modules that use prototypal inheritance to implement a > Stream api by inheriting from one of the Stream classes in node; but to me, > a Stream is really a set of behaviors/traits that I want my object to > implement, and using my one single prototype "bullet" to get it seems less > desirable to me than some way of informing the system that my object will > implement those behaviors/traits (along with possibly implementing other, > unrelated sets of behaviors). Interfaces let me do that, plus communicate > simply and effectively how to build something that plugs in to something > else, plus causes things that don't plug in correctly to break early and > obviously. > > Node seems to me to be an environment that allows developers to create > moderately complex systems quickly. And my sense (which could be wrong, > I'll admit up front) is that we seem to be in an early days stage where > lots of talented individual contributors are at work doing their own thing > -- happy to evaluate the ten different ways of doing anything, reading > other's code to get a sense of what is going on, etc. But I wonder if > going from moderately complex to really complex systems will require larger > teams, and more coordination, and if then we'll find we some formalizations > or tools to help people work together. (All this, of course, is just some > random noodlings from someone who is up late and jealous to have missed > nodeconf!) > -- 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 [email protected] To unsubscribe from this group, send email to [email protected] For more options, visit this group at http://groups.google.com/group/nodejs?hl=en?hl=en
