On Tue, Dec 1, 2009 at 1:43 PM, Jim Barrows <jim.barr...@gmail.com> wrote:
> Lift is getting very large. We've got singular names as lists, and plural
> names that aren't lists. We've got people calling roses red flowers, spades
> diamonds and other mass chaos. Well, it's not that bad, but you get the
> idea. This is an attempt to come up with a series of standard names to make
> working in lift easier, not only for the committers, but also (and more
> importantly) for you folks using it on a day to day basis.
>
> Achieving this means that there must be two things, a set of rules for
> naming conventions, and a process to make sure everyone is following those
> rules, and changing things when we mess it up.
>
> This thread is for discussing the process. I'll be starting another thread
> to discuss the rules, as well as another thread to discuss current names
> that we want to change.
> As always, if you don't speak up, you're not dissenting, and we welcome your
> views and ideas on how to do this!
>
> 1) Goal discussion (closes 8 Dec 09)
> 2) Identify changes, and put the list on the wiki (closes 15 Jan 10)
> 3) Convert the list to github tickets. This includes discussing setting
> priorities etc, assessing impacts etc etc to go into the ticket. (closes 29
> Jan 10)
> 4) Committers can then work the tickets into their own workflows, and
> everything would then follow the normal commit workflow from there.
> (committers work according to priority and impact etc)
> 5) Naming becomes a part of the normal review board process. However, if a
> committer thinks that the Name Caller needs to look at it earlier, or is
> having a hard time with naming something, by all means send an email. (
> date we add this to the process 29 Jan 10)
> 6) As we find things we missed, or better names, we work them through the
> github ticket and review system. ( date we add this to the process 29 Jan
> 10)
>
> --
> James A Barrows
The timeline looks good to me, with the exception of the fact that
we've already passed the first milestone!
With respect to goals, I have a few general suggestions.
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.
I also am attaching a start at some names I see as suboptimal from
S.scala, but since this thread isn't really for discussion of
individual naming issues (and such a thread doesn't yet exist) I
thought I'd go ahead and present my suggestions as a strawman for
format and what type of changes might be considered.
Kris
--
You received this message because you are subscribed to the Google Groups
"Lift" group.
To post to this group, send email to lift...@googlegroups.com.
To unsubscribe from this group, send email to
liftweb+unsubscr...@googlegroups.com.
For more options, visit this group at
http://groups.google.com/group/liftweb?hl=en.
module: lift-util
file: src/main/scala/net/liftweb/util/JsonCmd.scala
ResponseInfoHolder => ResponseMetadata
module: lift-webkit
file: src/main/scala/net/liftweb/http/S.scala
RewriteHolder => NamedRewrite
DispatchHolder => NamedDispatch
CookieHolder => Cookies
(\w+)HighLevelSessionDispatcher => \1SessionDispatcher (No LowLevel???)
? => % or $ (printf, jsp - what's the inspiration for ? as
localization/formatting?)
(\w+)_? => is\1 (underscore is used for enough things in Scala, let's not make
method names harder to read)
getHeader => getResponseHeader
getDocType => docType (change return type from tuple to case class with
sematically significant names?)
setDocType => docType_=
addCleanupFunc => onCleanup
functionLifespan_= parameter type Boolean => Lifespan (sealed trait Lifespan;
case object Session extends Lifespan; case object Request extends Lifespan)
functionLifespan_? => functionLifespan
attrs => snippetAttrs; return type should be something more informative than
List[(Either[String, (String, String)], String)]
prefixedAttrsToMap => snippetAttrMap
prefixedAttrsToMetadata => snippetAttrMetadata
mapToAttrs: Move to one of the util classes? No state dependencies in this
one...
getSessionAttribute(s: String) => containerSessionAttribute (to avoid confusion
with LiftSession) where containerSessionAttribute is a local object as defined
below
setSessionAttribute(s: String, v: String) => containerSessionAttribute(s:
String) = v; see below
object containerSessionAttribute {
def apply(name: String) = containerSession.flatMap(_.attribute(name) match
{case s: String => Full(s) case _ => Empty})
def update(name: String, value: String) =
containerSession.foreach(_.setAttribute(name, value))
def unset(name: String) = containerSession.foreach(_.removeAttribute(name))
}
fmapFunc => something else this is confusing for those familiar with fmap from
Haskell
clearCurrentNotices =>
Disambiguate S.loc / Loc; maybe use S.l instead (taking inspiration from
rails's h)
Disambiguate getNotices/getAllNotices/notices. Since there's a Notice type of
notice, maybe getNotices => messages ?
the current methods messages/noIdMessages/idMessages are all pure functions
that don't interact with state, maybe move them elsewhere?
NoticeType, maybe make a sealed trait w/case objects instead of Enumeration?
Why does S._statefulSnip not override nameSalt?
Needs better documentation, potential renames, or both:
currentAttrs*
locateMappedSnippet
booster (private, unused, candidate for removal?)
formFuncName
formGroup
*FuncHolder - these are widely used, but neither the names, types, or
documentation tell the novice what they're for
General suggestions:
Disambiguate/eliminate generic names: Field, Param,
