DISCUSSION: Documentation - Function Naming Conventions
Opened this issue · 0 comments
wanderslth commented
This issue is for discussing function naming conventions. Some goals:
- unique naming convention to avoid conflicts ("/lookup" and "/lookup" for intercom and crunchbase, respectively)
- standard naming convention for types of functions (lookup v list v convert)
- clear differentiation based on actual function (lookup on name v org)
- reasonable length
- clear parameter conventions (i.e., all these would work for a crunchbase lookup: query v search v name v domain)
Here are a list of the slugs for all of our current functions:
/cb-organizations", query
/cb-people", query
/intercom-user-lookup", email
/intercom-user-list", days
/intercom-event-list", user_id
/hubspot-contacts")
/wikipedia", search)
/currency-converter", amt, cur1, cur2, [date]
/currency-rates", cur, [date]
Thoughts:
- Service Name. Seems reasonable to me to begin each function with service name. The above conventions seem workable though an alternative would be to abbreviate it like crunchbase, with the assumption a) there are gonna be, what, at most 500 integrations we could possibly create? so overlap will be highly unlikely and b) users will copy/paste functions so full name doesn't really matter):
/cb-organizations", query
/int-user-lookup", email
/hub-contacts")
/wiki", search)
/cur-converter", amt, cur1, cur2, [date]
- Type Name. We don't have this issue now due to limited number of functions, but one can see we have multiple 'lookup' or 'enrichment' functions for crunchbase. The current naming conventions just ignore the type altogether. However, would we want type to be explicit, you could do something along these lines (variations here for dicussion):
/cb-enrich-org", query
/cb-enrich-people", query
/cb-lookup-org", query
/cb-lkup-people", query
/cb-list-investors, company
/cb-lst-events, company
/cb-convert-domain, name
- Function differentiation. Last part is core functionality differentiator. If you're doing a company lookup that will pull in all kinds of company information, then
-company
ororg
would probably be a reasonable differentiation.
/cb-enrich-org", query
/cb-enrich-people", query
- Parameter clarity. Currently function parameter descriptions vary widely (generic
search
andquery
v more specificemail
ordays
oruser_id
. My preference is to provide clarity when possible. For example with CB:
/cb-enrich-org", name
/cb-enrich-people", name
Following that, in parameter for the the org lookup, it currently says
Property | Type | Description | Required |
---|---|---|---|
query | string | Query string to use when searching for organizations | true |
But, this is not super clarifying to the end user, as it doesn't tell them to actually use the org name. A revision:
Property | Type | Description | Required |
---|---|---|---|
name | string | name of the organization | true |
or, if you offered domain names as an option in the query:
Property | Type | Description | Required |
---|---|---|---|
name | string | name or domain name of the organization | true |
Then, to further clarify in the sample usage, you give one of each:
=FLEX("YOUR_TEAM_NAME/cb-organizations", "crunchbase")
=FLEX("YOUR_TEAM_NAME/cb-organizations", "microsoft.com")
Summary:
I think we probably could come down to a basic three-tier naming convention (unless it's overkill):
servicename-type-descriptor
where we could utilize both abbreviations as well as clear descriptors/types
/cb-enrich-org", name
/int-enrich-user', email
/hub-list-leads" [note: I don't know what this one does?]
/wiki-enrich-description", title
/cur-convert", amt, cur1, cur2, [date]