Kris, can you look over and edit down your guidelines in the wiki? Thanks. On Fri, Dec 18, 2009 at 3:18 AM, Heiko Seeberger < [email protected]> wrote:
> Thank you for writing this up, Naftoli. > I edited the abbreviation section ... > > Heiko > > 2009/12/18 Naftoli Gugenheim <[email protected]> > > (Not sure why on Chrome the wiki article page is all centered. Reported it >> to Chrome.) >> >> Can everyone look over the article? Especially everyone "quoted" in it -- >> Kris, Jim, DPP, Heiko, and anyone who I may have missed -- can you make sure >> everything represents your opinion correctly? >> Then if there is any disagreement after everyone's opinion is clarified we >> need to make some decisions together. >> This should not take much time, but it's very valuable! Thanks. >> >> >> 2009/12/15 Naftoli Gugenheim <[email protected]> >> >> 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]<liftweb%[email protected]> >> . >> For more options, visit this group at >> http://groups.google.com/group/liftweb?hl=en. >> > > > > -- > Heiko Seeberger > > > My job: weiglewilczek.com > My blog: heikoseeberger.name > Follow me: twitter.com/hseeberger > OSGi on Scala: scalamodules.org > Lift, the simply functional web framework: liftweb.net > > -- > 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.
