incubator-tinkerpop git commit: added a style guide to the recipes cook book. CTR as the style model was DISCUSS in dev.

[ok...@apache.org]

Repository: incubator-tinkerpop
Updated Branches:
  refs/heads/master c61095f6b -> 66a82cece


added a style guide to the recipes cook book. CTR as the style model was DISCUSS in dev.


Project: http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/commit/66a82cec
Tree: http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/tree/66a82cec
Diff: http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/diff/66a82cec

Branch: refs/heads/master
Commit: 66a82cece601af2b04080e6b7a0f4da959a48078
Parents: c61095f
Author: Marko A. Rodriguez <ok...@gmail.com>
Authored: Thu May 19 08:12:56 2016 -0600
Committer: Marko A. Rodriguez <ok...@gmail.com>
Committed: Thu May 19 08:12:56 2016 -0600

----------------------------------------------------------------------
 CHANGELOG.asciidoc                    |  1 +
 docs/src/recipes/index.asciidoc       |  2 +
 docs/src/recipes/style-guide.asciidoc | 81 ++++++++++++++++++++++++++++++
 3 files changed, 84 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/blob/66a82cec/CHANGELOG.asciidoc
----------------------------------------------------------------------
diff --git a/CHANGELOG.asciidoc b/CHANGELOG.asciidoc
index 3de3702..628b4f4 100644
--- a/CHANGELOG.asciidoc
+++ b/CHANGELOG.asciidoc
@@ -26,6 +26,7 @@ image::https://raw.githubusercontent.com/apache/incubator-tinkerpop/master/docs/
 TinkerPop 3.2.1 (NOT OFFICIALLY RELEASED YET)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+* Added a traversal style guide to the recipes cookbook.
 * Fixed a bug in master-traversal traverser propagation.
 * Added useful methods for custom `VertexPrograms` to be used with `program()`-step.
 * Increased the test coverage around traverser propagation within a multi-job OLAP traversal.

http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/blob/66a82cec/docs/src/recipes/index.asciidoc
----------------------------------------------------------------------
diff --git a/docs/src/recipes/index.asciidoc b/docs/src/recipes/index.asciidoc
index fcda27b..8a64818 100644
--- a/docs/src/recipes/index.asciidoc
+++ b/docs/src/recipes/index.asciidoc
@@ -36,6 +36,8 @@ link:http://tinkerpop.apache.org/docs/x.y.z/tutorials/the-gremlin-console/[The G
 Traversal Recipes
 =================
 
+include::style-guide.asciidoc[]
+
 include::between-vertices.asciidoc[]
 
 include::shortest-path.asciidoc[]

http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/blob/66a82cec/docs/src/recipes/style-guide.asciidoc
----------------------------------------------------------------------
diff --git a/docs/src/recipes/style-guide.asciidoc b/docs/src/recipes/style-guide.asciidoc
new file mode 100644
index 0000000..14cbad9
--- /dev/null
+++ b/docs/src/recipes/style-guide.asciidoc
@@ -0,0 +1,81 @@
+////
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+////
+[[style-guide]]
+Style Guide
+-----------
+
+Gremlin is a data flow language where each new step concatenation alters the stream accordingly. This aspect of the
+language allows users to easily "build-up" a traversal (literally) step-by-step until the expected results are
+returned. For instance:
+
+[gremlin-groovy,modern]
+----
+g.V(1)
+g.V(1).out('knows')
+g.V(1).out('knows').out('created')
+g.V(1).out('knows').out('created').groupCount()
+g.V(1).out('knows').out('created').groupCount().by('name')
+----
+
+A drawback of building up a traversal is that users tend to create long, single line traversal that are hard to read.
+For simple traversals, a single line is fine. For complex traversals, there are few formatting patterns that should be followed
+which will yield cleaner, easier to understand traversals. For instance, the last traversal above would be written:
+
+[gremlin-groovy,modern]
+----
+g.V(1).out('knows').out('created').
+  groupCount().by('name')
+----
+
+Lets look at a complex traversal and analyze each line according to the recommended formatting rule is subscribes to.
+
+[gremlin-groovy,modern]
+----
+g.V().out('knows').out('created').  <1>
+  group().by('lang').by().          <2>
+    select('java').unfold().        <3>
+  in('created').hasLabel('person'). <4>
+  order().                          <5>
+    by(inE().count(),decr).         <6>
+    by('age',incr).
+  dedup().limit(10).values('name')  <7>
+----
+
+
+<1> A sequence of `ins().outs().filters().etc()` on a single line until it gets too long.
+<2> When a barrier (reducer, aggregator, etc.) is used, put it on a new line.
+<3> When a next line component is an "add on" to the previous line component, 2 space indent.
+The `select()`-step in this context is "almost like" a `by()`-modulator as its projecting data out of the `group()`.
+The `unfold()`-step is a data formatting necessity that should not be made too prominent.
+<4> Back to a series of `ins().outs().filters().etc()` on a single line.
+<5> `order()` is a barrier step and thus, should be on a new line.
+<6> If there is only one `by()`-modulator (or a series of short ones), keep it on one line, else each `by()` is a new line.
+<7> Back to a series `ins().outs().filters().etc()`.
+
+Style Guide Rules
+~~~~~~~~~~~~~~~~~
+
+A generalization of the specifics above are presented below.
+
+* Always use 2 space indent.
+* No newline should ever have the same indent as the line starting with the traversal source `g`.
+* Barrier steps should form line breaks unless they are simple (e.g. `sum()`).
+* Complex `by()`-modulators form indented "paragraphs."
+* Standard filters, maps, flatMaps remain on the same line until they get too long.
+
+Given the diversity of traversals and the complexities introduced by lambdas (for example), these rules will not always
+lead to optimal representations. However, by in large, the style rules above will help make 90% of traversals look great.