vavrtom commented on a change in pull request #36: QPID-8361: [Broker-J] Create
a developer guide for Qpid Broker-J
URL: https://github.com/apache/qpid-broker-j/pull/36#discussion_r324096799
##########
File path: doc/developer-guide/src/main/markdown/code-guide.md
##########
@@ -0,0 +1,446 @@
+# Qpid Broker-J Coding Standards
+
+This article documents the standard adopted for Java code in the Qpid project.
+All committers are expected to follow this standard.
+
+## Executive Summary
+
+The main things for layout purposes in the standard are:
+
+ * Indent using four spaces. No tabs.
+ * braces always go on new lines, e.g.
+```java
+if (x == 5)
+{
+ System.out.println("Hello");
+}
+```
+
+rather than
+
+```java
+if (x == 5} {
+ System.out.println("Hello");
+}
+```
+
+Always add braces, e.g.
+
+```java
+ if (x == 5)
+ {
+ System.out.println("Hello");
+ }
+```
+rather than
+
+```java
+if (x == 5}
+ System.out.println("Hello");
+```
+
+Fields prefixed with underscores, e.g. `_messageCount`
+
+Spaces after keywords but no spaces either before or after parentheses in
method calls, e.g.
+
+```java
+ if (x == 5)
+```
+
+rather than
+
+```java
+ if(x==5)
+```
+
+but
+
+```java
+ foo.bar(4, 5)
+```
+
+rather than
+
+```java
+ foo.bar( 4, 5 )
+```
+
+## Details
+
+### Introduction
+
+This document describes two types of coding standard:
+
+1. **Mandatory** standards must be followed at all times.
+2. **Recommended** standards should in general be followed but in particular
cases may be omitted
+ where the programmer feels that there is a good reason to do so.
+
+Code that does not adhere to mandatory standards will not pass the automated
checks
+(or a code review if the guideline is not stylistic).
+
+### Source files
+
+This section defines the general rules associated with the contents of a Java
source file and the order
+in which the each part should be presented. No rules on programming style,
naming conventions or indentation are given here.
+
+1. Java source files must have a ".java" suffix (this will be enforced by the
compiler) [mandatory].
+2. The basename of a Java source file must be the same as the public class
defined therein
+ (this will be enforced by the compiler) [mandatory].
+3. Only one class should be defined per source file (except for inner classes
and one-shot uses
+ where the non-public class cannot conceivably be used outside of its
context) [mandatory].
+4. Source files should not exceed 1500 lines [recommended].
+5. No line in a source file should exceed 120 characters [mandatory].
+6. The sections of a source file should be presented in the following order
[mandatory]:
+ * File information comment (see rule 7 below).
+ * Package name (see rules 1 to 3 in the section 2.1 above and rule 8 below).
+ * Imports (see rules 9 to 10 below).
+ * Other class definitions.
+ * Public class definition.
+7. Do not use automatically expanded log or revision number provided by your
source code management system
+ unless it provides a facility to avoid "false conflicts" when doing merges
due simply to revision number changes
+ (which happens, for example, with cvs when branches are used). [mandatory]
+8. Every class that is to be released must be a member of a package
[mandatory].
+ Rationale: classes that are not explicitly put in a package are placed in
the unnamed package by the compiler.
+ Therefore as the classes from many developers will be being placed in the
same package the likelihood of a name
+ clash is greatly increased.
+9. All class imports from the same package should be grouped together. A
single blank line should separate imports
Review comment:
I would like to suggest to add another import rule to forbid wildcard
imports as they could lead to conflicts between classes in different packages
with the same name.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
With regards,
Apache Git Services
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@qpid.apache.org
For additional commands, e-mail: dev-h...@qpid.apache.org
