spark-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Xiangrui Meng <men...@gmail.com>
Subject Re: multi-line comment style
Date Mon, 09 Feb 2015 20:25:28 GMT
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