kafka-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From guozh...@apache.org
Subject kafka-site git commit: Add coding guidelines for Streams API
Date Tue, 05 Sep 2017 20:48:10 GMT
Repository: kafka-site
Updated Branches:
  refs/heads/asf-site 07a0b4045 -> b99a8350b

Add coding guidelines for Streams API

Author: Matthias J. Sax <matthias@confluent.io>

Reviewers: Guozhang Wang <wangguoz@gmail.com>

Closes #73 from mjsax/streams-coding-guidelines

Project: http://git-wip-us.apache.org/repos/asf/kafka-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/kafka-site/commit/b99a8350
Tree: http://git-wip-us.apache.org/repos/asf/kafka-site/tree/b99a8350
Diff: http://git-wip-us.apache.org/repos/asf/kafka-site/diff/b99a8350

Branch: refs/heads/asf-site
Commit: b99a8350bb83033006f2b92ca4dcb222c2f5685e
Parents: 07a0b40
Author: Matthias J. Sax <matthias@confluent.io>
Authored: Tue Sep 5 13:48:08 2017 -0700
Committer: Guozhang Wang <wangguoz@gmail.com>
Committed: Tue Sep 5 13:48:08 2017 -0700

 coding-guide.html | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/coding-guide.html b/coding-guide.html
index 887fed5..4b83004 100644
--- a/coding-guide.html
+++ b/coding-guide.html
@@ -102,6 +102,47 @@
 		<li>We should attempt to maintain API compatibility when possible, though at this
point in the project's lifecycle it is more important to make things good rather than avoid
+		<h2>Streams API</h2>
+		<p>Kafka's Streams API (aka Kafka Streams) uses a few more additional coding guidelines.
+                   All contributors should follow these the get a high quality and uniform
code base.
+                   Some rules help to simplify PR reviews and thus make the life of all contributors
+		<ul>
+			<li>Use <code>final</code> when possible.
+                            This holds for all class members, local variables, loop variables,
and method parameters.</li>
+			<li>Write modular and thus testable code. Refactor if necessary!</li>
+			<li>Avoid large PRs (recommended is not more the 500 lines per PR).
+                            Many JIRAs requires larger code changes; thus, split the work
in multiple PRs and create according sub-task on the JIRA to track the work.</li>
+			<li>All public APIs must have JavaDocs.</li>
+			<li>Verify if JavaDocs are still up to date or if they need to be updated.</li>
+			<li>JavaDocs: Write grammatically correct sentences and use punctuation marks correctly.</li>
+			<li>Use proper markup (e.g., <code>{@code null}</code>).</li>
+			<li>Update the documentation on the Kafka webpage (i.e., within folder <code>docs/</codes>.
+                            Doc changes are not additional work (i.e. no follow up PRs) but
part of the actual PR (can also be a sub-tasks).</li>
+			<li>Testing:
+				<ul>
+					<li>Use self-explaining method names (e.g., <code>shouldNotAcceptNullAsTopicName()</code>).</li>
+					<li>Each test should cover only a single case.</li>
+					<li>Keep tests as short as possible (i.e., write crisp code).</li>
+					<li>Write tests for all possible parameter values.</li>
+					<li>Don't use reflections but rewrite your code (reflections indicate bad design
in the first place).</li>
+					<li>Use annotations such as <code>@Test(expected = SomeException.class)</code>
only for single line tests.</li>
+				</ul>
+			</li>
+			<li>Code formatting (those make Github diffs easier to read and thus simplify code
+				<ul>
+					<li>No line should be longer than 120 characters.</li>
+					<li>Use a "single parameter per line" formatting when defining methods (also for
methods with only 2 parameters).</li>
+					<li>If a method call is longer than 120 characters, switch to a single parameter
per line formatting
+                                            (instead of just breaking it into two lines only).</li>
+					<li>For JavaDocs, start a new line for each new sentence.</li>
+					<li>Avoid unnecessary reformatting.</li>
+					<li>If reformatting is neccessary, do a minor PR (either upfront or as follow
+				</ul>
+			</li>
+			<li>Run <code>./gradlew clean chechstyleMain checkstyleTest</code> before
opening/updating a PR.</li>
+			<li>Help reviewing!
+                            No need to be shy; if you can contribute code, you know enough
to comment on the work of others.</li>
+		</ul>
 	// Show selected style on nav item
 	$(function() { $('.b-nav__project').addClass('selected'); });

View raw message