[OpenLayers-Dev] constructor signatures
Tim Schaub
tschaub at opengeo.org
Fri Jun 18 10:41:22 EDT 2010
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 at openlayers.org
> http://openlayers.org/mailman/listinfo/dev
--
Tim Schaub
OpenGeo - http://opengeo.org
Expert service straight from the developers.
More information about the Dev
mailing list