I compiled much of this thread into http://wiki.github.com/dpp/liftweb/about-naming-conventions in raw form. As we continue to discuss the naming goals and guidelines and vote or decide on controversial goals, that wiki page should become more consolidated and less of a copy-paste of a discussion. :)
On Mon, Dec 14, 2009 at 6:32 PM, Kris Nuttycombe <[email protected]>wrote: > On Mon, Dec 14, 2009 at 12:31 PM, David Pollak > <[email protected]> wrote: > > Folks, > > > > Lift allows developers to create web sites that are: > > > > Reliable (which includes secure) > > Maintainable/concise > > Highly interactive > > Easy to build > > High Performance > > Easy to on-board (initial understanding of the APIs) > > > > Lift's APIs should reflect these rank-ordered goals. Some of these goals > > are in tension with each other. For example, easy on-boarding (e.g., > longer > > method names, more traditional imperative style) is in tension with > concise. > > > > There's also a very diverse Lift community. > > > > I use Emacs for a lot of my Lift coding. I know folks who use TextMate > for > > Lift coding. Having long method names assumes the use of an IDE which > has > > name completion. Lift's APIs must serve both communities. > > People are coming to Lift from Java, Ruby, PHP, and other backgrounds. > > Assuming Scala conventions rather than a "best choice" for naming does a > > dis-service to the polygots. Further, most of Scala's API conventions > > except for the collections stuff is not in my opinion that well thought > out > > or consistent. > > Many of Lift's APIs have evolved correctly based on actual usage > patterns. > > For example, the initially counter-intuitive use of apply to set fields > and > > vars works far better than any other mechanism, especially when chaining > > calls. I've tried many different mechanisms (e.g., update(), Pascal > style > > :=, set(), etc.) for setting fields and the one that everybody gravitated > to > > was apply(). > > > > We also have to consider the existing code base. I've personally got > 150K > > lines of Lift-code under management. If we start breaking APIs without a > > compelling reason, it costs me money and it costs my clients less of my > > time. What's the impact to various different current users of Lift of > > breaking APIs without a compelling reason (and "I like this name better > than > > that name" or "this name is more consistent" are not compelling reasons.) > > So, my criteria for any name changes (and this is not open to any type of > > negotiation and I've been 100% consistent about this since the discussion > > began) is: > > > > If the name change can be accomplished with a deprecation of the old name > > without breaking any existing APIs, then the name change can be the > "better" > > name. > > If the name change is internal to Lift or is in a little-used feature > (e.g., > > Kris's API changes in Loc) such that very few projects will likely be > > impacted by a name change and those that are impacted are sufficiently > savvy > > that they will understand the change and be able to make it in a matter > of > > minutes. > > Any class name or object name change that does not meet the above > criteria > > must be compelling. For example, we changed from Scala Actors to Lift > > Actors. This was a substantial amount of breakage, but there were no > > alternatives and the Scala Actor memory retention issues were materially > > impacting many different sites and we had worked on various attempted > > solutions over a 10 month period. If we're going to break without > > deprecation and the breakage is going to impact a substantial part of the > > Lift community, there must be a compelling reason to make the breakage. > > > > On Sun, Dec 13, 2009 at 10:49 AM, Kris Nuttycombe > > <[email protected]> wrote: > >> > >> To this point, the only goals that have been recommended for this > >> effort are those that I've noted below: > >> > >> >> 1) Remove ambiguity wherever possible! There are a number of places > >> >> where very similar names are used to refer to utterly different > >> >> things. > >> > >> >> 2) As an aide removing ambiguity, consider outlawing or eliminating > >> >> extremely generic names, or else establish a single way in which a > >> >> given name will be used across Lift. Examples are Field, Info, > Holder, > >> >> etc. > > > > In general, this is okay, but if there's a FooHolder that holds a Foo, > > what's wrong with that kind of naming? > > Holder is probably the least problematic of these. The only issue I > have with it is that FooHolder doesn't say anything about why you > might want to have that particular kind of container (or indeed have a > container at all) for a Foo. In some sense, every object that contains > data is a holder - and I don't think "StringHolder" makes much sense; > why does FooHolder? > > >> > >> >> 3) Avoid making the name of the return type part of the name of the > >> >> method. The types should tell the story as much as possible, except > in > >> >> the case where multiple methods varying only in return type would > >> >> exist (illegal overloads) > > > > I'd be interested in understanding what the specific examples are, but > I'm > > not sure I'm on board with this. Sometimes getLiftResponse is a lot more > > meaningful than get. > > There were a couple of examples of this in S that I thought were > suspect, but we can address those individually. In general I think > this suggestion boils down to DRY. > > >> > >> >> 4) Prefer Scala-style accessors and mutators. > > > > I disagree. This is one where I have tried a lot of different accessors > and > > mutators and the current crop is the best of breed. Sure, it's a little > > different, but it is much better. > > I'm talking more about the instances where you've got Scala classes > with setX and getX rather than x and x_= - S is inconsistent and > sometimes uses getX, sometimes uses x > > >> > >> In general, the principle goal of this effort must be improving the > >> clarity of the Lift API for both new adopters and for maintainers. We > >> now have two days before the "goal discussion" closes. If anyone has > >> any additional objectives they'd like to voice before this window > >> closes, please do so now. I'd like to hold a vote on the proposals > >> above as well as any other objectives folks may have tomorrow, so that > >> any -1's can be ironed out before the 15th. > >> > >> Kris > > -- > > You received this message because you are subscribed to the Google Groups > "Lift" group. > To post to this group, send email to [email protected]. > To unsubscribe from this group, send email to > [email protected]<liftweb%[email protected]> > . > For more options, visit this group at > http://groups.google.com/group/liftweb?hl=en. > > > -- You received this message because you are subscribed to the Google Groups "Lift" group. To post to this group, send email to [email protected]. To unsubscribe from this group, send email to [email protected]. For more options, visit this group at http://groups.google.com/group/liftweb?hl=en.
