Gregers Gram Rygg wrote: > How about max 3 arguments for any constructor or method in 3.0? Need > more arguments, use an options object. >
The problem with rules like this (max of X) is that we don't know ahead of time how many properties we'll want to use when configuring a new instance. We don't know how many will be required. We don't know how many will be optional. In the lifetime of a major version, the configuration logic of a constructor changes. You could say that when adding a new constructor, it cannot have more than three arguments, and that the third one *has* to be an object that can later accept any number of member properties. I think three is arbitrary (and silly). If we accept that we'll learn more than we know now and that our code will change in the lifetime of a major version, going with a single argument is the simplest way to allow backwards compatibility without having weird (null, null, config) constructors. > The only downside I see with options objects are that it gets more > difficult to read the source code to see what the available options > are. One approach to solve this would be to use fake option classes > for Natural Docs. > * options - {GridLayerOptions} Hashtable of extra options to tag > onto the layer > > Then document the GridLayerOptions in the same file (bottom?): > /** > * Class: GridLayerOptions > * Inherits: <LayerOptions> > * > * Properties: > * name - {String} *required* > * url - {String} *required* > * params - {Object} *required* > * ..... > */ > > It will be difficult to keep the arguments up to date for the class > you inherit from, but maybe it is enough to just document the options > specific for this class, and link to the inherited options "class" > somehow. I'm not very familiar with NaturalDocs, so I don't know if > "Class" is the best keyword for the options object, but I like it > better than some of the docs today (see RootContainer's constructor). > This is similar to what Google Maps does in their documentation: > http://code.google.com/apis/maps/documentation/javascript/reference.html#MapTypeControlOptions > > Options objects can have required properties. Just throw an Error if > it's missing. Maybe a required options array on the prototype, so it > can be done in a generic manner. > > Errors thrown from a minified script is quite useless, since it > doesn't say anything about class name or line number in original > source. Maybe it's time to integrate a simple logging framework? Can > start a separate thread to discuss this. > > > Best regards, > Gregers > _______________________________________________ > Dev mailing list > Dev@openlayers.org > http://openlayers.org/mailman/listinfo/dev -- Tim Schaub OpenGeo - http://opengeo.org Expert service straight from the developers. _______________________________________________ Dev mailing list Dev@openlayers.org http://openlayers.org/mailman/listinfo/dev