Patrick, I sympathize with your sensibility here, and at face value,
there's very little daylight between (a) a rule comprising small set of
enumerated items and (b) a guideline followed by the same set as examples.
My suggestion had a non-obvious tl;dr thesis behind it, so allow me to show
my cards :)
First, rules can be costly for the rule makers to create and maintain to
ensure necessity and sufficiency, and can unintentionally encourage
mischievous, often tedious arguments to work around those rules. In the
area of coding style, even at Google (at least when I was there), we had
guides rather than rules. It turns out that guidelines are also easier to
socialize and enforce than enumerated rules. <strawman_humor>A Google
search for "coding style guide" returns 15.7 million results, while that
for "coding style rule" has 6.6M, and most of *those* are articles about
"coding style guide".</strawman_humor>
More importantly, I've found Spark's to be one of the best
socially-engineered communities I've participated in. It is quite helpful
and welcoming to newcomers while (not paradoxically) comprising one of the
highest median quality of participants, per my calibration of, e.g., the
various meetups I've gone to in the SF Bay Area. This community
friendliness and mutual regard are not accidental and have contributed in
part to Spark's success to date. It seems quite tolerant of "newbies" and
implicitly recognizes that there may be a lot of valuable expertise and
interesting use cases we can learn from the person behind that
idiotic-sounding question, who might go on to contribute valuable PRs. I've
yet to see the acronym RTFM used in anger here. Now, "rules" don't
automatically negate that, but they can be discouraging to navigate ("Have
I broken some rule?") and misused as devices to shoot others ("You've just
broken our rule #178.S4.P2). I'd rather see those things kept to a minimum,
in locked cabinets.
For the above reasons, I would suggest, for Spark, guidelines over rules
whenever feasible & tolerable, certainly in the area of coding style.
Cheers,
--
Christopher T. Nguyen
Co-founder & CEO, Adatao <http://adatao.com>
linkedin.com/in/ctnguyen
On Wed, Feb 19, 2014 at 8:37 AM, Patrick Wendell <pwend...@gmail.com> wrote:
> +1 overall.
>
> Christopher - I agree that once the number of rules becomes large it's
> more efficient to pursue a "use your judgement" approach. However,
> since this is only 3 cases I'd prefer to wait to see if it grows.
>
> The concern with this approach is that for newer people, contributors,
> etc it's hard for them to understand what good judgement is. Many are
> new to scala, so explicit rules are generally better.
>
> - Patrick
>
> On Wed, Feb 19, 2014 at 12:19 AM, Reynold Xin <r...@databricks.com> wrote:
> > Yes, the case you brought up is not a matter of readability or style. If
> it
> > returns a different type, it should be declared (otherwise it is just
> > wrong).
> >
> >
> > On Wed, Feb 19, 2014 at 12:17 AM, Mridul Muralidharan <mri...@gmail.com
> >wrote:
> >
> >> You are right.
> >> A degenerate case would be :
> >>
> >> def createFoo = new FooImpl()
> >>
> >> vs
> >>
> >> def createFoo: Foo = new FooImpl()
> >>
> >> Former will cause api instability. Reynold, maybe this is already
> >> avoided - and I understood it wrong ?
> >>
> >> Thanks,
> >> Mridul
> >>
> >>
> >>
> >> On Wed, Feb 19, 2014 at 12:44 PM, Christopher Nguyen <c...@adatao.com>
> >> wrote:
> >> > Mridul, IIUUC, what you've mentioned did come to mind, but I deemed it
> >> > orthogonal to the stylistic issue Reynold is talking about.
> >> >
> >> > I believe you're referring to the case where there is a specific
> desired
> >> > return type by API design, but the implementation does not, in which
> >> case,
> >> > of course, one must define the return type. That's an API requirement
> and
> >> > not just a matter of readability.
> >> >
> >> > We could add this as an NB in the proposed guideline.
> >> >
> >> > --
> >> > Christopher T. Nguyen
> >> > Co-founder & CEO, Adatao <http://adatao.com>
> >> > linkedin.com/in/ctnguyen
> >> >
> >> >
> >> >
> >> > On Tue, Feb 18, 2014 at 10:40 PM, Reynold Xin <r...@databricks.com>
> >> wrote:
> >> >
> >> >> +1 Christopher's suggestion.
> >> >>
> >> >> Mridul,
> >> >>
> >> >> How would that happen? Case 3 requires the method to be invoking the
> >> >> constructor directly. It was implicit in my email, but the return
> type
> >> >> should be the same as the class itself.
> >> >>
> >> >>
> >> >>
> >> >>
> >> >> On Tue, Feb 18, 2014 at 10:37 PM, Mridul Muralidharan <
> mri...@gmail.com
> >> >> >wrote:
> >> >>
> >> >> > Case 3 can be a potential issue.
> >> >> > Current implementation might be returning a concrete class which we
> >> >> > might want to change later - making it a type change.
> >> >> > The intention might be to return an RDD (for example), but the
> >> >> > inferred type might be a subclass of RDD - and future changes will
> >> >> > cause signature change.
> >> >> >
> >> >> >
> >> >> > Regards,
> >> >> > Mridul
> >> >> >
> >> >> >
> >> >> > On Wed, Feb 19, 2014 at 11:52 AM, Reynold Xin <r...@databricks.com
> >
> >> >> wrote:
> >> >> > > Hi guys,
> >> >> > >
> >> >> > > Want to bring to the table this issue to see what other members
> of
> >> the
> >> >> > > community think and then we can codify it in the Spark coding
> style
> >> >> > guide.
> >> >> > > The topic is about declaring return types explicitly in public
> APIs.
> >> >> > >
> >> >> > > In general I think we should favor explicit type declaration in
> >> public
> >> >> > > APIs. However, I do think there are 3 cases we can avoid the
> public
> >> API
> >> >> > > definition because in these 3 cases the types are self-evident &
> >> >> > repetitive.
> >> >> > >
> >> >> > > Case 1. toString
> >> >> > >
> >> >> > > Case 2. A method returning a string or a val defining a string
> >> >> > >
> >> >> > > def name = "abcd" // this is so obvious that it is a string
> >> >> > > val name = "edfg" // this too
> >> >> > >
> >> >> > > Case 3. The method or variable is invoking the constructor of a
> >> class
> >> >> and
> >> >> > > return that immediately. For example:
> >> >> > >
> >> >> > > val a = new SparkContext(...)
> >> >> > > implicit def rddToAsyncRDDActions[T: ClassTag](rdd: RDD[T]) = new
> >> >> > > AsyncRDDActions(rdd)
> >> >> > >
> >> >> > >
> >> >> > > Thoughts?
> >> >> >
> >> >>
> >>
>
