+1 to what Andrew said, I think both make sense in different situations and trusting developer discretion here is reasonable.
On Mon, Feb 9, 2015 at 1:48 PM, Andrew Or <and...@databricks.com> wrote: > In my experience I find it much more natural to use // for short multi-line > comments (2 or 3 lines), and /* */ for long multi-line comments involving > one or more paragraphs. For short multi-line comments, there is no reason > not to use // if it just so happens that your first line exceeded 100 > characters and you have to wrap it. For long multi-line comments, however, > using // all the way looks really awkward especially if you have multiple > paragraphs. > > Thus, I would actually suggest that we don't try to pick a favorite and > document that both are acceptable. I don't expect developers to follow my > exact usage (i.e. with a tipping point of 2-3 lines) so I wouldn't enforce > anything specific either. > > 2015-02-09 13:36 GMT-08:00 Reynold Xin <r...@databricks.com>: > > > Why don't we just pick // as the default (by encouraging it in the style > > guide), since it is mostly used, and then do not disallow /* */? I don't > > think it is that big of a deal to have slightly deviations here since it > is > > dead simple to understand what's going on. > > > > > > On Mon, Feb 9, 2015 at 1:33 PM, Patrick Wendell <pwend...@gmail.com> > > wrote: > > > > > 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 > > > >>>> > > > > >>>> > > > > >>>> > > > > > >
