[Grok-dev] Re: On the Grok API

[Tres Seaver]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Martin Aspeli wrote:
> Luciano Ramalho wrote:
>> When I first started reading the source of apps made with Grok, I
>> found code like this a little strange:
>>
>> #################
>>
>> class WorkflowIndexes(grok.Indexes):
>>     grok.site(Blog)
>>     grok.context(IWorkflowState)
>>     grok.name('entry_catalog')
>>
>>     workflow_state = index.Field(attribute='getState')
>>     workflow_id = index.Field(attribute='getId')
>>
>> #################
>>
>> What bothered me were those calls to grok functions right after the
>> class declaration. Those calls have a declarative intent, and perhaps
>> would be class annotations if Python's syntax allowed.
>>
>> Then I remembered that in Ruby on Rails, they have similar declarative calls:
>>
>> #################
>> class User < ActiveRecord::Base
>>     validates_presence_of :name
>>     validates_uniqueness_of :name
>>     attr_accessor :password_confirmation
>>
>>     def self.authenticate(name, password)
>>         user = self.find_by_name(name)
>>         if user
>>             expected_password = encrypted_password(password, user.salt)
>>             if user.hashed_password != expected_password
>>                 user = nil
>>             end
>>         end
>>         user
>>     end
>>     # (... more code would follow ...)
>> #################
>>
>> As you can see, in Rails they use the wider syntatic variability of
>> Ruby to make the declarative statements look different from regular
>> function calls by omitting the parenthesis around the args in the
>> declarative calls, but using parenthesis in the usual function calls.
>>
>> In order to make this distinction explicit in Grok, we could use a
>> different namespace for those declarative functions. For example, we
>> could have:
>>
>> #################
>> from grok import declare
>>
>> class WorkflowIndexes(grok.Indexes):
>>     declare.site(Blog)
>>     declare.context(IWorkflowState)
>>     declare.name('entry_catalog')
>>
>>     workflow_state = index.Field(attribute='getState')
>>     workflow_id = index.Field(attribute='getId')
>> #################
>>
>> Of course, instead of declare we could have another word. Some shorter
>> alternatives would be let or bind.
>>
>> This whole idea is in keeping with a usability principle stated by
>> Donald Norman, that similar things should look similar, and different
>> things should look different.
>>
>> I maybe too new to Grok to be making these kinds of suggestions, but
>> the whole issue just occurred to me because I am new, and I figure one
>> of my missions during this summer is to give you this perspective.
> 
> I'm not sure it warrants a change at this point, and it may be 
> contentious, but +1 from me. I very much like these kinds of conventions 
> (not the configuration type of convention, but just coding conventions) 
> to make the intent of code clear. The 'grok' namespace contains a lot of 
> things!

- -1 from me.  The point of the "facade" module is that it contains
everything you need.  Adding another name does not make this any clearer.


Tres.
- --
===================================================================
Tres Seaver          +1 540-429-0999          tseaver at palladion.com
Palladion Software   "Excellence by Design"    http://palladion.com
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFGaJMR+gerLs4ltQ4RArM0AKC269PjEt5qVWkeb3b36G2Y2h/7iwCeJ/MJ
pIQDrOY9iQGhMWRQJNTjRtg=
=IULQ
-----END PGP SIGNATURE-----