spark-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Patrick Wendell <pwend...@gmail.com>
Subject Re: multi-line comment style
Date Mon, 09 Feb 2015 21:33:48 GMT
Clearly there isn't a strictly optimal commenting format (pro's and
cons for both '//' and '/*'). My thought is for consistency we should
just chose one and put in the style guide.

On Mon, Feb 9, 2015 at 12:25 PM, Xiangrui Meng <mengxr@gmail.com> wrote:
> Btw, I think allowing `/* ... */` without the leading `*` in lines is
> also useful. Check this line:
> https://github.com/apache/spark/pull/4259/files#diff-e9dcb3b5f3de77fc31b3aff7831110eaR55,
> where we put the R commands that can reproduce the test result. It is
> easier if we write in the following style:
>
> ~~~
> /*
>  Using the following R code to load the data and train the model using
> glmnet package.
>
>  library("glmnet")
>  data <- read.csv("path", header=FALSE, stringsAsFactors=FALSE)
>  features <- as.matrix(data.frame(as.numeric(data$V2), as.numeric(data$V3)))
>  label <- as.numeric(data$V1)
>  weights <- coef(glmnet(features, label, family="gaussian", alpha = 0,
> lambda = 0))
>  */
> ~~~
>
> So people can copy & paste the R commands directly.
>
> Xiangrui
>
> On Mon, Feb 9, 2015 at 12:18 PM, Xiangrui Meng <mengxr@gmail.com> wrote:
>> I like the `/* .. */` style more. Because it is easier for IDEs to
>> recognize it as a block comment. If you press enter in the comment
>> block with the `//` style, IDEs won't add `//` for you. -Xiangrui
>>
>> On Wed, Feb 4, 2015 at 2:15 PM, Reynold Xin <rxin@databricks.com> wrote:
>>> We should update the style doc to reflect what we have in most places
>>> (which I think is //).
>>>
>>>
>>>
>>> On Wed, Feb 4, 2015 at 2:09 PM, Shivaram Venkataraman <
>>> shivaram@eecs.berkeley.edu> wrote:
>>>
>>>> FWIW I like the multi-line // over /* */ from a purely style standpoint.
>>>> The Google Java style guide[1] has some comment about code formatting tools
>>>> working better with /* */ but there doesn't seem to be any strong arguments
>>>> for one over the other I can find
>>>>
>>>> Thanks
>>>> Shivaram
>>>>
>>>> [1]
>>>>
>>>> https://google-styleguide.googlecode.com/svn/trunk/javaguide.html#s4.8.6.1-block-comment-style
>>>>
>>>> On Wed, Feb 4, 2015 at 2:05 PM, Patrick Wendell <pwendell@gmail.com>
>>>> wrote:
>>>>
>>>> > Personally I have no opinion, but agree it would be nice to standardize.
>>>> >
>>>> > - Patrick
>>>> >
>>>> > On Wed, Feb 4, 2015 at 1:58 PM, Sean Owen <sowen@cloudera.com>
wrote:
>>>> > > One thing Marcelo pointed out to me is that the // style does not
>>>> > > interfere with commenting out blocks of code with /* */, which
is a
>>>> > > small good thing. I am also accustomed to // style for multiline,
and
>>>> > > reserve /** */ for javadoc / scaladoc. Meaning, seeing the /* */
style
>>>> > > inline always looks a little funny to me.
>>>> > >
>>>> > > On Wed, Feb 4, 2015 at 3:53 PM, Kay Ousterhout <
>>>> kayousterhout@gmail.com>
>>>> > wrote:
>>>> > >> Hi all,
>>>> > >>
>>>> > >> The Spark Style Guide
>>>> > >> <
>>>> > https://cwiki.apache.org/confluence/display/SPARK/Spark+Code+Style+Guide
>>>> >
>>>> > >> says multi-line comments should formatted as:
>>>> > >>
>>>> > >> /*
>>>> > >>  * This is a
>>>> > >>  * very
>>>> > >>  * long comment.
>>>> > >>  */
>>>> > >>
>>>> > >> But in my experience, we almost always use "//" for multi-line
>>>> comments:
>>>> > >>
>>>> > >> // This is a
>>>> > >> // very
>>>> > >> // long comment.
>>>> > >>
>>>> > >> Here are some examples:
>>>> > >>
>>>> > >>    - Recent commit by Reynold, king of style:
>>>> > >>
>>>> >
>>>> https://github.com/apache/spark/commit/bebf4c42bef3e75d31ffce9bfdb331c16f34ddb1#diff-d616b5496d1a9f648864f4ab0db5a026R58
>>>> > >>    - RDD.scala:
>>>> > >>
>>>> >
>>>> https://github.com/apache/spark/blob/master/core/src/main/scala/org/apache/spark/rdd/RDD.scala#L361
>>>> > >>    - DAGScheduler.scala:
>>>> > >>
>>>> >
>>>> https://github.com/apache/spark/blob/master/core/src/main/scala/org/apache/spark/scheduler/DAGScheduler.scala#L281
>>>> > >>
>>>> > >>
>>>> > >> Any objections to me updating the style guide to reflect this?
 As
>>>> with
>>>> > >> other style issues, I think consistency here is helpful (and
>>>> formatting
>>>> > >> multi-line comments as "//" does nicely visually distinguish
code
>>>> > comments
>>>> > >> from doc comments).
>>>> > >>
>>>> > >> -Kay
>>>> > >
>>>> > > ---------------------------------------------------------------------
>>>> > > To unsubscribe, e-mail: dev-unsubscribe@spark.apache.org
>>>> > > For additional commands, e-mail: dev-help@spark.apache.org
>>>> > >
>>>> >
>>>> > ---------------------------------------------------------------------
>>>> > To unsubscribe, e-mail: dev-unsubscribe@spark.apache.org
>>>> > For additional commands, e-mail: dev-help@spark.apache.org
>>>> >
>>>> >
>>>>

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@spark.apache.org
For additional commands, e-mail: dev-help@spark.apache.org


Mime
View raw message