[Lift] Goals for type and method renaming for Lift 2.0 - was: Open discussion on Lift Name Calling practices

[Kris Nuttycombe]

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.

>> 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)

>> 4) Prefer Scala-style accessors and mutators.

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

[Naftoli Gugenheim]

I agree very strongly that this is the principle goal. A good name expresses what it refers to succintly, and if that is not enough to inform one exactly what it is, once one learns what it is then he sees how "obvious" it is from the name and it is an efficient, effective reminder. (If something can be obvious after you learn it, but hopefully you know what I mean. :) )
Similarly if you know what you want to do it would be easy to remember its name.
I wish I had more time to work on this, but in any case there isn't much to talk about until the goals are finalized. Maybe it would be worthwhile to compose a list of potential goals, even ones that are questionable, and hold a vote on each of them on the list?
In any case, I think it's unrealistic to hope to have a perfect API in all of LIft by 2.0, but on the other hand too unambitious to just deal with names as they are questioned, if they are. We want Lift to have a good reputation in terms of API design.
Maybe we should decide to tackle one module at a time, one package at a time, and maybe even one class at a time, systematically. If we can cover net.liftweb.http by 2.0, it would be superb. But I think systematic is very important, because otherwise the results will be half-baked.
So I vote for an on going, but systematic process--it need not have time constraints but someone needs to take one name at a time, throw all the guidelines at it (which btw should end up in a wiki IMHO), and then raise discussion on the list if applicable. It doesn't matter how long it takes, because slowly but surely we will see clear results.
Similarly, Review Board posters and reviewers should accept responsibility to follow all naming guidelines as best as possible.
Hoping to hear feedback. :)

-------------------------------------

--

You received this message because you are subscribed to the Google Groups "Lift" group.
To post to this group, send email to lif...@googlegroups.com.
To unsubscribe from this group, send email to liftweb+u...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/liftweb?hl=en.

[Heiko Seeberger]

2009/12/13 Kris Nuttycombe <kris.nu...@gmail.com>

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.

>> 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)

>> 4) Prefer Scala-style accessors and mutators.

Thank you Kris for writing up these goals. I would like to add another one:

5) Avoid using abbreviations

 

In general, the principle goal of this effort must be improving the
clarity of the Lift API for both new adopters and for maintainers.

100% agreed! 

In order to make Lift even more popular it is essential to ease adoption. Often folks require better documentation and we all know that the code (the API) is the first and best source of documentation.

Heiko

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

[Heiko Seeberger]

And here is another one:

6) Use names related to the "nature" of the thing being named: We should be able to know what a type is or a method does from reading its name.

[David Pollak]

Folks,

Lift allows developers to create web sites that are:

1. Reliable (which includes secure)
2. Maintainable/concise
3. Highly interactive
4. Easy to build
   
5. High Performance
6. 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 <kris.nu...@gmail.com> 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?
 

>> 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.
 

>> 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.
 

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 lif...@googlegroups.com.
To unsubscribe from this group, send email to liftweb+u...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/liftweb?hl=en.

--
Lift, the simply functional web framework http://liftweb.net
Beginning Scala http://www.apress.com/book/view/1430219890
Follow me: http://twitter.com/dpp
Surf the harmonics

[David Pollak]

On Sun, Dec 13, 2009 at 10:39 PM, Heiko Seeberger <heiko.s...@googlemail.com> wrote:

2009/12/13 Kris Nuttycombe <kris.nu...@gmail.com>

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.

>> 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)

>> 4) Prefer Scala-style accessors and mutators.

Thank you Kris for writing up these goals. I would like to add another one:

5) Avoid using abbreviations

I disagree.  When coding with a non-IDE, abbreviations make life much easier.
 

 

In general, the principle goal of this effort must be improving the
clarity of the Lift API for both new adopters and for maintainers.

100% agreed! 

In order to make Lift even more popular it is essential to ease adoption. Often folks require better documentation and we all know that the code (the API) is the first and best source of documentation.

Heiko

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 lif...@googlegroups.com.
To unsubscribe from this group, send email to liftweb+u...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/liftweb?hl=en.

[Timothy Perrett]

This is such a preference. Most people use IDEs, I personally dont, but I would still choose clarity and marginal verbosity over less typing. A classic is some places in lift we call it "calc" and other palces its "calculator"

Cheers, Tim

[Naftoli Gugenheim]

Many of these things are subjective. I'm wondering if maybe we should first agree on *guidelines* as is happening now, and then as we go along systematically through central parts of lift such as net.liftweb.http, holding up names against the guidelines, work out a document of *conventions*--a more specific set of rules, e.g., when or whether to use calc or calculator. This way the conventions are influenced (not dictated though!) by core lift APIs, and then other parts can be held up to that measuring stick and make them conform to consistency.


-------------------------------------

[Jim Barrows]

I snipped some stuff.

On Mon, Dec 14, 2009 at 12:34 PM, David Pollak <feeder.of...@gmail.com> wrote:

On Sun, Dec 13, 2009 at 10:39 PM, Heiko Seeberger <heiko.s...@googlemail.com> wrote:

2009/12/13 Kris Nuttycombe <kris.nu...@gmail.com>

5) Avoid using abbreviations

I disagree.  When coding with a non-IDE, abbreviations make life much easier.

I agree with David, abbreviations are better.  When I'm trying to get something out of my head and into code, I don't want things getting in my way.  2 things in this scenario get in my way.  1) autocomplete is slow 2) typing is slow.

Here's something else to think about on this issue.  A good typist, familiar with their material can type faster then most code completions can operate.  In studying data entry folks at UofP, I noticed something about the auto-complete functionality that wasn't obvious to me before.  It's not how fast the code complete pops up that slow you down.  It's the mental shift from typing to reading that takes the most time.  You always have to verify that what the auto-complete is going to use is correct.  This almost always takes more time then typing it yourself (assuming an expert typist).

--
James A Barrows

[Heiko Seeberger]

5) Avoid using abbreviations

I disagree.  When coding with a non-IDE, abbreviations make life much easier.

I agree with David, abbreviations are better.  When I'm trying to get something out of my head and into code, I don't want things getting in my way.  2 things in this scenario get in my way.  1) autocomplete is slow 2) typing is slow.

Here's something else to think about on this issue.  A good typist, familiar with their material can type faster then most code completions can operate.  In studying data entry folks at UofP, I noticed something about the auto-complete functionality that wasn't obvious to me before.  It's not how fast the code complete pops up that slow you down.  It's the mental shift from typing to reading that takes the most time.  You always have to verify that what the auto-complete is going to use is correct.  This almost always takes more time then typing it yourself (assuming an expert typist).

My concern is not at all coding speed which mostly is faster than thinking speed (at least for stupid pea-brains like me). I am concerned about how intuitive the Lift API, hence how fast folks will be familiar with it.

To be more precise: I like abbreviations for really obvious stuff like RequestVar (everybody would know VarIABLES). But I do not like ... well I cannot find an example right now for an abbreviation in Lift that I do not like => Thus I guess this is more a general principle and Lift behaves quite well in this regard.

 

Heiko

[Naftoli Gugenheim]

I'm not sure you can generalize whether abbreviations are good or bad. It depends how obvious their meaning is. No one in favor of abreviations wants to replace say JSONResponseType (if such a name exists) with JRT! Nor does anyone want to replace JSON with JavaScriptObjectNotation. Everyone agrees it's not black and white and a balance is needed between verbosity, clarity, and conciseness.
I propose that a this stage we try to vote and agree on as many black and white goals as possible, to create a list of guidelines. Resolving conflicts between guidelines maybe should wait until afterwards to establish conventions. This may be influenced by precedent as well as reason and discussion, and the conventions should then be used to help enforce consistency.
For a black and white guideline, does anyone disagree with the following? "An abbreviation which is either commonly recognized or used commonly in Lift names, may be used as part of a name; otherwise it should not be."
Again, of course it leaves plenty of gray area--that's on purpose; the gray area can later be addressed by "conventions."

-------------------------------------

Jim Barrows<jim.b...@gmail.com> wrote:

I snipped some stuff.

On Mon, Dec 14, 2009 at 12:34 PM, David Pollak <
feeder.of...@gmail.com> wrote:

>
>
> On Sun, Dec 13, 2009 at 10:39 PM, Heiko Seeberger <
> heiko.s...@googlemail.com> wrote:
>
>> 2009/12/13 Kris Nuttycombe <kris.nu...@gmail.com>

>> 5) Avoid using abbreviations
>>
>
> I disagree. When coding with a non-IDE, abbreviations make life much
> easier.
>

I agree with David, abbreviations are better. When I'm trying to get
something out of my head and into code, I don't want things getting in my
way. 2 things in this scenario get in my way. 1) autocomplete is slow 2)
typing is slow.

Here's something else to think about on this issue. A good typist, familiar
with their material can type faster then most code completions can operate.
In studying data entry folks at UofP, I noticed something about the
auto-complete functionality that wasn't obvious to me before. It's not how
fast the code complete pops up that slow you down. It's the mental shift
from typing to reading that takes the most time. You always have to verify
that what the auto-complete is going to use is correct. This almost always
takes more time then typing it yourself (assuming an expert typist).



>
>>
>>

>>> In general, the principle goal of this effort must be improving the
>>> clarity of the Lift API for both new adopters and for maintainers.
>>
>>
>> 100% agreed!
>>
>> In order to make Lift even more popular it is essential to ease adoption.
>> Often folks require better documentation and we all know that the code (the
>> API) is the first and best source of documentation.
>>

>> Heiko
>>
>> 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 lif...@googlegroups.com.
>> To unsubscribe from this group, send email to

>> liftweb+u...@googlegroups.com<liftweb%2Bunsu...@googlegroups.com>
>> .

>> For more options, visit this group at
>> http://groups.google.com/group/liftweb?hl=en.
>>
>
>
>
> --
> Lift, the simply functional web framework http://liftweb.net
> Beginning Scala http://www.apress.com/book/view/1430219890
> Follow me: http://twitter.com/dpp
> Surf the harmonics
>
> --
> You received this message because you are subscribed to the Google Groups
> "Lift" group.
>
> To post to this group, send email to lif...@googlegroups.com.
> To unsubscribe from this group, send email to

> liftweb+u...@googlegroups.com<liftweb%2Bunsu...@googlegroups.com>
> .

> For more options, visit this group at
> http://groups.google.com/group/liftweb?hl=en.
>



--
James A Barrows

[Naftoli Gugenheim]

Do you have benchmarks comparing the differences in time?
Just kidding. :)
But I would like to point out, I understand your position, but I think many people would use the exact same argument against abbreviations, if they make it take longer to figure out or remember what their called!
Some people use autocomplete not to save energy from typing 3 letters but to see a list of "what can I do with this object?--let's see, it has a currentUserId member with a return type of X--that must be what I want!"
And some people are better at remembering logical names than shorter names--different people have are different kinds of learners etc. etc.
I'm not negating your point; I'm just pointing out that everything has to be balanced, and perhaps consistency is even more important than the exact balance desired...

[Naftoli Gugenheim]

[Kris Nuttycombe]

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

[Naftoli Gugenheim]

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. :)

[Naftoli Gugenheim]

(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 <nafto...@gmail.com>

[Jonathan Ferguson]

2009/12/15 David Pollak <feeder.of...@gmail.com>

5) Avoid using abbreviations

I disagree.  When coding with a non-IDE, abbreviations make life much easier.

When using abbreviations, could the abbreviation be documented even it if it the most mind numbingly obvious abbreviation as there will always 

be people from a different background who don't grok it.

Cheers 

Jono

[Naftoli Gugenheim]

Is that sufficiently expressed in the wiki article draft (look for "Jim")? If not, what would you add?

-------------------------------------
Jonathan Ferguson<jo...@spiralarm.com> wrote:

2009/12/15 David Pollak <feeder.of...@gmail.com>

Cheers

Jono

--

[Heiko Seeberger]

Thank you for writing this up, Naftoli.

I edited the abbreviation section ...

Heiko

2009/12/18 Naftoli Gugenheim <nafto...@gmail.com>

--
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

[Naftoli Gugenheim]

Kris, can you look over and edit down your guidelines in the wiki? Thanks.