API driver methods and parameters

["marios@redhat.com" <ma...@redhat.com>]

Hi, I am (finally) back onto working on the blobstore. I wanted to get 
some opinions (alternatively, find out if anyone feels strongly either 
way) about the driver method signatures. This is not terribly important 
but its a choice all the same.

So far most driver methods (i.e. defined in base_driver.rb) look like:

" def method_name(credentials, opts=nil) "

where opts hash will contain any of the required parameters (e.g. an 
'id' parameter for filtering a list of images). I have tried to follow 
this style as much as possible for blobstore thus far. However it seems 
silly for some methods not to explicate the parameters.

An obvious one is 'create_blob' where you need to supply the bucket 
name, blob name and the blob data. So I guess the question is should we 
have:

"def create_blob(credentials, bucket_id, blob_id, blob_data)"

OR

"def create_blob(credentials, opts = nil)"
{and  where opts: opts['bucket_id'], opts['blob_id'], opts['blob_data']}



marios

Re: API driver methods and parameters

["marios@redhat.com" <ma...@redhat.com>]

Hi Ladislav, thanks for taking the time. I think thats a really good 
point and well made - backwards compatibility is very important to us, 
especially now that we are thinking about getting some kind of stable 
release cycle going. However the obvious trade-off here is that we make 
our code less clear/harder to follow/more like magic :) if we are hiding 
all our parameters. I don't know which is the overriding concern.

marios

On 12/11/10 15:19, Ladislav Martincik wrote:
> Hi,
>
> On Nov 12, 2010, at 2:11 PM, marios@redhat.com wrote:
>
>> Hi, I am (finally) back onto working on the blobstore. I wanted to get some opinions (alternatively, find out if anyone feels strongly either way) about the driver method signatures. This is not terribly important but its a choice all the same.
>>
>> So far most driver methods (i.e. defined in base_driver.rb) look like:
>>
>> " def method_name(credentials, opts=nil)"
>>
>> where opts hash will contain any of the required parameters (e.g. an 'id' parameter for filtering a list of images). I have tried to follow this style as much as possible for blobstore thus far. However it seems silly for some methods not to explicate the parameters.
>>
>> An obvious one is 'create_blob' where you need to supply the bucket name, blob name and the blob data. So I guess the question is should we have:
>>
>> "def create_blob(credentials, bucket_id, blob_id, blob_data)"
>>
>> OR
>>
>> "def create_blob(credentials, opts = nil)"
>> {and  where opts: opts['bucket_id'], opts['blob_id'], opts['blob_data']}
>>
>>
>
> Personally I would vote and I believe that having less arguments is better. Few reasons:
> 1) It's less likely that when you change the order of arguments you would have to change all the occurrences in the code
> 2) Whenever you decide to remove add new argument you have to also change all occurrences
>
> Also known as "Connascence of Position (CoP)". You can read more about it here: http://urgetopunt.com/2009/03/27/sor-connascence.html
>
> Hope that makes sense and good argument.
>
> -- Ladislav
>
>

Re: API driver methods and parameters

[Ladislav Martincik <lm...@redhat.com>]

Hi,

On Nov 12, 2010, at 2:11 PM, marios@redhat.com wrote:

> Hi, I am (finally) back onto working on the blobstore. I wanted to get some opinions (alternatively, find out if anyone feels strongly either way) about the driver method signatures. This is not terribly important but its a choice all the same.
> 
> So far most driver methods (i.e. defined in base_driver.rb) look like:
> 
> " def method_name(credentials, opts=nil) "
> 
> where opts hash will contain any of the required parameters (e.g. an 'id' parameter for filtering a list of images). I have tried to follow this style as much as possible for blobstore thus far. However it seems silly for some methods not to explicate the parameters.
> 
> An obvious one is 'create_blob' where you need to supply the bucket name, blob name and the blob data. So I guess the question is should we have:
> 
> "def create_blob(credentials, bucket_id, blob_id, blob_data)"
> 
> OR
> 
> "def create_blob(credentials, opts = nil)"
> {and  where opts: opts['bucket_id'], opts['blob_id'], opts['blob_data']}
> 
> 

Personally I would vote and I believe that having less arguments is better. Few reasons:
1) It's less likely that when you change the order of arguments you would have to change all the occurrences in the code
2) Whenever you decide to remove add new argument you have to also change all occurrences

Also known as "Connascence of Position (CoP)". You can read more about it here: http://urgetopunt.com/2009/03/27/sor-connascence.html

Hope that makes sense and good argument.

-- Ladislav