I'm just about to add some new API functionality to Heist, and I'm looking for suggestions on function names. I made a gist of the still-evolving code available here https://gist.github.com/871084/0bf97781a6d443e1215cf376974f1d220f38d83b. In the gist history you can see the evolution of names and implementations.
To kick-start the discussion here's a little history. The job at hand is to create functions that simplify the syntax required for a splice to use its node's children as the view. This is best illustrated with some example markup. <pre> <recentPostSummaries> <h3><a href="$(postUrl)"><postTitle/></a></h3> <div class="post"><postSummary/></div> </recentPostSummaries> </pre> This example assumes recentPostSummaries is a splice that retrieves recent posts. But instead of letting the splice define the way posts should be rendered, we pass the desired view into the splice as the contents of the <recentPostSummaries> tag. We rely on the splice to bind appropriate dynamic content to new splices postUrl, postTitle, and postSummary before our view markup gets rendered. The runChildren function in the above gist provides the most basic building block of functionality--it gets the child nodes and runs them. Other names we've thought of for this function are things like children, include, runParamChildren, runChildNodes, runView, etc. The viewWith function adds a parameter containing a list of splices to bind before running the child nodes. This is the core function for implementing splices like recentPostSummaries. The name came from a desire to establish some more concise terminology. In this context (that of a programmer writing splices) I like using the term "view" to refer to the child nodes that are passed into a splice for use as the splice's view. Jystic created this gist demonstrating how some different name choices for the viewWith function would look in actual use https://gist.github.com/871207/626edac1537b67fd75a5d9c350c68b830d06e2d2. I like the brevity of the name "viewWith". It also establishes a convention that works pretty well for the other related functions we've defined. But it has been argued that the name could be confusing to newcomers because the term "view" is ambiguous and probably overused already. IMO the next best name in jystic's list is "runChildrenWith". It is more descriptive, but longer and more cumbersome. The names of the rest of the functions in the gist will probably be closely related to whatever we name viewWith. mapSplices at the end is just a generic version of concatMap for splices. We'll certainly consider better names for that as well, but I think "mapSplices" is pretty good. I would like to release a new version of Heist with this functionality as soon as possible, but I think it's very important that we have good names for these concepts first. In my experience good names can be a huge benefit because they allow clear, concise communication and form the substrate upon which these ideas will grow. What are your thoughts about the names mentioned here? Do you have any better suggestions? _______________________________________________ Snap mailing list [email protected] http://mailman-mail5.webfaction.com/listinfo/snap
