Repository: spark-website Updated Branches: refs/heads/asf-site 4f72689a4 -> 7c294769a
Add Databricks Scala guide to "Code Style Guide" Closes #139 Project: http://git-wip-us.apache.org/repos/asf/spark-website/repo Commit: http://git-wip-us.apache.org/repos/asf/spark-website/commit/7c294769 Tree: http://git-wip-us.apache.org/repos/asf/spark-website/tree/7c294769 Diff: http://git-wip-us.apache.org/repos/asf/spark-website/diff/7c294769 Branch: refs/heads/asf-site Commit: 7c294769aec8eb17b409d2cf915715f95c1068c8 Parents: 4f72689 Author: hyukjinkwon <[email protected]> Authored: Sat Aug 25 13:46:00 2018 +0800 Committer: hyukjinkwon <[email protected]> Committed: Sun Aug 26 17:33:43 2018 +0800 ---------------------------------------------------------------------- contributing.md | 168 +------------------------------------------- site/contributing.html | 164 +----------------------------------------- 2 files changed, 6 insertions(+), 326 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/spark-website/blob/7c294769/contributing.md ---------------------------------------------------------------------- diff --git a/contributing.md b/contributing.md index bb26896..77f57fb 100644 --- a/contributing.md +++ b/contributing.md @@ -389,173 +389,11 @@ lower case latter and S4 objects/methods are allowed. <a href="http://www.oracle.com/technetwork/java/codeconvtoc-136057.html";>Oracle's Java code conventions</a>. Many Scala guidelines below also apply to Java. - For Scala code, Apache Spark follows the official -<a href="http://docs.scala-lang.org/style/";>Scala style guide</a>, but with the following changes, below. - -<h3>Line Length</h3> - -Limit lines to 100 characters. The only exceptions are import statements (although even for -those, try to keep them under 100 chars). - -<h3>Indentation</h3> - -Use 2-space indentation in general. For function declarations, use 4 space indentation for its -parameters when they don't fit in a single line. For example: - -```scala -// Correct: -if (true) { - println("Wow!") -} - -// Wrong: -if (true) { - println("Wow!") -} - -// Correct: -def newAPIHadoopFile[K, V, F <: NewInputFormat[K, V]]( - path: String, - fClass: Class[F], - kClass: Class[K], - vClass: Class[V], - conf: Configuration = hadoopConfiguration): RDD[(K, V)] = { - // function body -} - -// Wrong -def newAPIHadoopFile[K, V, F <: NewInputFormat[K, V]]( - path: String, - fClass: Class[F], - kClass: Class[K], - vClass: Class[V], - conf: Configuration = hadoopConfiguration): RDD[(K, V)] = { - // function body -} -``` - -<h3>Code documentation style</h3> - -For Scala doc / Java doc comment before classes, objects and methods, use Java docs style -instead of Scala docs style. - -```scala -/** This is a correct one-liner, short description. */ - -/** - * This is correct multi-line JavaDoc comment. And - * this is my second line, and if I keep typing, this would be - * my third line. - */ - -/** In Spark, we don't use the ScalaDoc style so this - * is not correct. - */ -``` - -For inline comment with the code, use `//` and not `/* .. */`. - -```scala -// This is a short, single line comment - -// This is a multi line comment. -// Bla bla bla - -/* - * Do not use this style for multi line comments. This - * style of comment interferes with commenting out - * blocks of code, and also makes code comments harder - * to distinguish from Scala doc / Java doc comments. - */ - -/** - * Do not use scala doc style for inline comments. - */ -``` - -<h3>Imports</h3> - -Always import packages using absolute paths (e.g. `scala.util.Random`) instead of relative ones -(e.g. `util.Random`). In addition, sort imports in the following order -(use alphabetical order within each group): - -- `java.*` and `javax.*` -- `scala.*` -- Third-party libraries (`org.*`, `com.*`, etc) -- Project classes (`org.apache.spark.*`) - -The <a href="https://plugins.jetbrains.com/plugin/7350";>IntelliJ import organizer plugin</a> -can organize imports for you. Use this configuration for the plugin (configured under -Preferences / Editor / Code Style / Scala Imports Organizer): - -```scala -import java.* -import javax.* - -import scala.* - -import * - -import org.apache.spark.* -``` - -<h3>Infix Methods</h3> - -Don't use infix notation for methods that aren't operators. For example, instead of -`list map func`, use `list.map(func)`, or instead of `string contains "foo"`, use -`string.contains("foo")`. This is to improve familiarity to developers coming from other languages. - -<h3>Curly Braces</h3> - -Put curly braces even around one-line `if`, `else` or loop statements. The only exception is if -you are using `if/else` as an one-line ternary operator. - -```scala -// Correct: -if (true) { - println("Wow!") -} - -// Correct: -if (true) statement1 else statement2 - -// Wrong: -if (true) - println("Wow!") -``` - -<h3>Return Types</h3> - -Always specify the return types of methods where possible. If a method has no return type, specify -`Unit` instead in accordance with the Scala style guide. Return types for variables are not -required unless the definition involves huge code blocks with potentially ambiguous return values. - -```scala -// Correct: -def getSize(partitionId: String): Long = { ... } -def compute(partitionId: String): Unit = { ... } - -// Wrong: -def getSize(partitionId: String) = { ... } -def compute(partitionId: String) = { ... } -def compute(partitionId: String) { ... } - -// Correct: -val name = "black-sheep" -val path: Option[String] = - try { - Option(names) - .map { ns => ns.split(",") } - .flatMap { ns => ns.filter(_.nonEmpty).headOption } - .map { n => "prefix" + n + "suffix" } - .flatMap { n => if (n.hashCode % 3 == 0) Some(n + n) else None } - } catch { - case e: SomeSpecialException => - computePath(names) - } -``` +<a href="http://docs.scala-lang.org/style/";>Scala style guide</a> and +<a href="https://github.com/databricks/scala-style-guide";>Databricks Scala guide</a>. The latter is preferred. <h3>If in Doubt</h3> If you're not sure about the right style for something, try to follow the style of the existing codebase. Look at whether there are other examples in the code that use your feature. Feel free -to ask on the `[email protected]` list as well. +to ask on the `[email protected]` list as well and/or ask committers. http://git-wip-us.apache.org/repos/asf/spark-website/blob/7c294769/site/contributing.html ---------------------------------------------------------------------- diff --git a/site/contributing.html b/site/contributing.html index b28d93d..1dd4823 100644 --- a/site/contributing.html +++ b/site/contributing.html @@ -644,173 +644,15 @@ lower case latter and S4 objects/methods are allowed.</li> <a href="http://www.oracle.com/technetwork/java/codeconvtoc-136057.html";>Oracle’s Java code conventions</a>. Many Scala guidelines below also apply to Java.</li> <li>For Scala code, Apache Spark follows the official -<a href="http://docs.scala-lang.org/style/";>Scala style guide</a>, but with the following changes, below.</li> +<a href="http://docs.scala-lang.org/style/";>Scala style guide</a> and +<a href="https://github.com/databricks/scala-style-guide";>Databricks Scala guide</a>. The latter is preferred.</li> </ul> -<h3>Line Length</h3> - -<p>Limit lines to 100 characters. The only exceptions are import statements (although even for -those, try to keep them under 100 chars).</p> - -<h3>Indentation</h3> - -<p>Use 2-space indentation in general. For function declarations, use 4 space indentation for its -parameters when they don’t fit in a single line. For example:</p> - -<pre><code class="language-scala">// Correct: -if (true) { - println("Wow!") -} - -// Wrong: -if (true) { - println("Wow!") -} - -// Correct: -def newAPIHadoopFile[K, V, F <: NewInputFormat[K, V]]( - path: String, - fClass: Class[F], - kClass: Class[K], - vClass: Class[V], - conf: Configuration = hadoopConfiguration): RDD[(K, V)] = { - // function body -} - -// Wrong -def newAPIHadoopFile[K, V, F <: NewInputFormat[K, V]]( - path: String, - fClass: Class[F], - kClass: Class[K], - vClass: Class[V], - conf: Configuration = hadoopConfiguration): RDD[(K, V)] = { - // function body -} -</code></pre> - -<h3>Code documentation style</h3> - -<p>For Scala doc / Java doc comment before classes, objects and methods, use Java docs style -instead of Scala docs style.</p> - -<pre><code class="language-scala">/** This is a correct one-liner, short description. */ - -/** - * This is correct multi-line JavaDoc comment. And - * this is my second line, and if I keep typing, this would be - * my third line. - */ - -/** In Spark, we don't use the ScalaDoc style so this - * is not correct. - */ -</code></pre> - -<p>For inline comment with the code, use <code>//</code> and not <code>/* .. */</code>.</p> - -<pre><code class="language-scala">// This is a short, single line comment - -// This is a multi line comment. -// Bla bla bla - -/* - * Do not use this style for multi line comments. This - * style of comment interferes with commenting out - * blocks of code, and also makes code comments harder - * to distinguish from Scala doc / Java doc comments. - */ - -/** - * Do not use scala doc style for inline comments. - */ -</code></pre> - -<h3>Imports</h3> - -<p>Always import packages using absolute paths (e.g. <code>scala.util.Random</code>) instead of relative ones -(e.g. <code>util.Random</code>). In addition, sort imports in the following order -(use alphabetical order within each group):</p> - -<ul> - <li><code>java.*</code> and <code>javax.*</code></li> - <li><code>scala.*</code></li> - <li>Third-party libraries (<code>org.*</code>, <code>com.*</code>, etc)</li> - <li>Project classes (<code>org.apache.spark.*</code>)</li> -</ul> - -<p>The <a href="https://plugins.jetbrains.com/plugin/7350";>IntelliJ import organizer plugin</a> -can organize imports for you. Use this configuration for the plugin (configured under -Preferences / Editor / Code Style / Scala Imports Organizer):</p> - -<pre><code class="language-scala">import java.* -import javax.* - -import scala.* - -import * - -import org.apache.spark.* -</code></pre> - -<h3>Infix Methods</h3> - -<p>Don’t use infix notation for methods that aren’t operators. For example, instead of -<code>list map func</code>, use <code>list.map(func)</code>, or instead of <code>string contains "foo"</code>, use -<code>string.contains("foo")</code>. This is to improve familiarity to developers coming from other languages.</p> - -<h3>Curly Braces</h3> - -<p>Put curly braces even around one-line <code>if</code>, <code>else</code> or loop statements. The only exception is if -you are using <code>if/else</code> as an one-line ternary operator.</p> - -<pre><code class="language-scala">// Correct: -if (true) { - println("Wow!") -} - -// Correct: -if (true) statement1 else statement2 - -// Wrong: -if (true) - println("Wow!") -</code></pre> - -<h3>Return Types</h3> - -<p>Always specify the return types of methods where possible. If a method has no return type, specify -<code>Unit</code> instead in accordance with the Scala style guide. Return types for variables are not -required unless the definition involves huge code blocks with potentially ambiguous return values.</p> - -<pre><code class="language-scala">// Correct: -def getSize(partitionId: String): Long = { ... } -def compute(partitionId: String): Unit = { ... } - -// Wrong: -def getSize(partitionId: String) = { ... } -def compute(partitionId: String) = { ... } -def compute(partitionId: String) { ... } - -// Correct: -val name = "black-sheep" -val path: Option[String] = - try { - Option(names) - .map { ns => ns.split(",") } - .flatMap { ns => ns.filter(_.nonEmpty).headOption } - .map { n => "prefix" + n + "suffix" } - .flatMap { n => if (n.hashCode % 3 == 0) Some(n + n) else None } - } catch { - case e: SomeSpecialException => - computePath(names) - } -</code></pre> - <h3>If in Doubt</h3> <p>If you’re not sure about the right style for something, try to follow the style of the existing codebase. Look at whether there are other examples in the code that use your feature. Feel free -to ask on the <code>[email protected]</code> list as well.</p> +to ask on the <code>[email protected]</code> list as well and/or ask committers.</p> </div> </div> --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
