Inform an API user if he did something stupid: To identify if the value undefined has actually been passed by your method, you can check the arguments object: Documenting APIs One of the hardest tasks of software development is documenting things.
Choose one style and keep that style — even if you find yourself disliking it at some point in the future. It is not necessary to compress getters and setters into a single method in order to create a fluid interface — it boils down to personal preference.
Passing data by reference is often used to keep memory overhead low, values passed by reference can be changed anywhere outside your API and affect state within. How could your API help the developer to reduce the noise of repeating method calls?
A couple of topics will be touching upon jQuery for demonstration, yet this article is neither about jQuery nor about writing plugins for it. Say we had a number of elements for which we want to set the default value: An interval starts with a date and ends with a date.
Find a line of wording you like and stick with it. Try to be as consistent about this as humanly possible. You should be writing code that explains itself. Handling Arguments How your methods accept data is more important than making them chain-able.
Some APIs are so flexible they are too smart for their own good. This style was chosen to keep examples brief.
Treating undefined as an Expected Value There will come a time when undefined is a value that your API actually expects to be given for setting an attribute. Take a look at the signatures of jQuery. Events Events come naturally when working with the DOM.
But beware — not all Errors are helping the debugging developer: Whatever choice you make, keep your API consistent! This is usually not what we want or expect. A date is not necessarily connected to an interval.
To provide fluency, you have to think about code streams — where are you coming from and where you are headed. While method chaining is a pretty generic thing that you can easily make your code do, handling arguments is not.
What do you make.