[OpenLayers-Dev] constructor signatures

[Tim Schaub]

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.