For example, here is how you state your column definitions for a DataTable widget instance:
var myColumnDefs = [ {key:"Title", label:"Name", sortable:true, formatter:formatUrl}, {key:"Phone"}, {key:"City"}, {key:"Rating.AverageRating", label:"Rating", formatter:formatRating, sortable:true} ];
and later on you can say:
var myDataTable = new YAHOO.widget.DataTable("json", myColumnDefs, ...
I'll try to explain why I find this topic so important that it has already influenced my style of programming.
Expectations instead of steps
A configuration like this is a contract between the programmer and the API. The programmer writes down it's expectations from the program and not the exact steps of how to reach that goal. As I came from C# I see this style as an interface. I like interfaces because they are clean, and hiding implementation details.
Config objects vs. parameters
I think there is a huge difference between giving configuration for something versus giving parameters (at least for me). I see parameters as a superset of configurations because parameters can contain not only expectations but details demanding you to understand the code behind the function.
For example, consider this function:
function rangeLowerCase(from, to, elements){
var els = [];
for(var i = from; i < to; i++){
els.push(elements[i].toLowerCase());
}
return els;
}
rangeLowerCase(0, 5, ["H", "E", "L", "L", "O"]); //-> ["h", "e", "l", "l", "o"]
When we call rangeLowerCase above we have to give the beginning of the process explicitly with the "from" parameter. But that's pops up lots of questions. Where the implementation starts? From zero or 1? At the end of the day, we have to read the code or documentation to understand what's going on.
So the "from" is not a configuration but a parameter. In my vision a configuration would be like
rangeLowerCase({ "take-first" : 5, "list" : elements});
Here you don't need to read the implementation but you know what will happen... okay that's not true, but at least you can expect it. You don't have to know where we want the first index to start. It's totally upon the developer of the API.
Elegancy
How many lines of code do you have to change when you want to modify its behaviour? I always ask this question when talking about elegancy and I try to hold that number very low in my solutions. Considering the previous example, it is self-explaining how many lines you have to change to take the first 10 elements instead of 5.
To sum it up, a configuration should improve the understanding of the code at first glance so improving the maintainability and clarity. It's more about expectations rather than implementation, so it's closer to the customer's thoughts, and easier to maintain.
