DISCUSSION: Documentation - Function Naming Conventions

[wanderslth]

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 or org would probably be a reasonable differentiation.

/cb-enrich-org", query
/cb-enrich-people", query

• Parameter clarity. Currently function parameter descriptions vary widely (generic search and query v more specific email or days or user_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]