[Grok-dev] Re: On the Grok API

[Martin Aspeli]

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!

Martin


-- 
Acquisition is a jealous mistress