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 <men...@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 <men...@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 <r...@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 < >>> shiva...@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 <pwend...@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 <so...@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 < >>>> kayousterh...@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-unsubscr...@spark.apache.org >>>> > > For additional commands, e-mail: dev-h...@spark.apache.org >>>> > > >>>> > >>>> > --------------------------------------------------------------------- >>>> > To unsubscribe, e-mail: dev-unsubscr...@spark.apache.org >>>> > For additional commands, e-mail: dev-h...@spark.apache.org >>>> > >>>> > >>>> --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@spark.apache.org For additional commands, e-mail: dev-h...@spark.apache.org
