qpid-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "ASF GitHub Bot (Jira)" <j...@apache.org>
Subject [jira] [Commented] (QPID-8361) [Broker-J] Create a developer guide for Qpid Broker-J
Date Tue, 17 Sep 2019 13:20:00 GMT

    [ https://issues.apache.org/jira/browse/QPID-8361?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16931439#comment-16931439
] 

ASF GitHub Bot commented on QPID-8361:
--------------------------------------

alex-rufous commented on 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_r325161064
 
 

 ##########
 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
+   from different packages [recommended].
+10. Use javadoc tags and use HTML mark-up to enhance the readability of the output files
[mandatory].
+
+### Java Elements
+
+This section gives advice on coding the various elements of the Java programming language.
+
+#### Class definitions
+
+This section gives guidelines for class and interface definitions in Java.
+The term class in this section is used more broadly to mean class and interface:
+
+1. Class names should start with a capital letter with every subsequent word capitalised,
+   for example: `DataProcessor` [mandatory].
+2. All classes should be preceded by a javadoc comment describing the purpose of the class
[recommended].
+3. Class-level javadoc comments should specify the thread-safety of the class [recommended].
+4. The name of exception classes should end in the word exception, for example: UnknownMungeException
[mandatory].
+5. Class names should in general not be overloaded. For example, defining a class "com.foo.bar.String"
+    should be avoided as there is already a class "java.lang.String" [recommended].
+    Rationale: adhering to this rule reduces the likelihood of confusion and means that the
use of fully qualified
+    class names should not be required.
+6. The definition of the primary class (i.e. the class with the same name as the java file)
should start in column 0
+   of the source file. Inner class definitions should be indented 4 spaces more than their
enclosing class [mandatory].
+7. Declare a class as final only if specialisation will never be required and improved performance
is essential.
+   With modern JVMs there in fact may be no performance advantage. Warning: use of final
limits code reuse [mandatory].
+8. For all but simplest classes the following methods should have useful definitions [recommended]:
+    ```java
+        public boolean equals(Object obj)
+        public int hashCode()
+        public String toString()
+    ```
+9. The order of presentation of the sections in a class should be [mandatory]:
+   * Variables
+   * Methods
+
+#### Variables
+This section gives guidelines for class and instance variable definitions in Java.
+In this section if a rule uses the term variable rather than instance variable or class variable,
+then the rule applies to both types of variable.
+
+1. The order of presentation of variables in a class definition should be [recommended]:
+    * private, protected, public: static final variables (aka constant class variables).
+    * private, protected, public: static variables (aka class variables).
+    * private, protected, public: final variables (aka constant instance variables).
+    * private, protected, public: variables (aka instance variables).
+    It should be noted that as javadoc will automatically order variables in a consistent
manner,
+    rigid adherence to this rule is not necessary.
+2. Variable modifiers should be presented in the following order: static, final, transient,
volatile [mandatory].
+3. The names of static final variables should be upper case with subsequent words prefixed
with an underscore [mandatory].
+   For example:
+    ```java
+    public static final int NOT_FOUND = -1;
+    ```
+4. When a subclass refers to a static final variable defined in a parent class, access should
be qualified
+    by specifying the defining class name [mandatory].
+    For example: use `ParentClass.MAX` rather than `MAX`.
+5. The names of variables (other that static final) should start with a lower case letter.
+   Any words that are contained in the rest of the variable name should be capitalised [mandatory].
+    For example:
+    ```java
+    String name;
+    String[] childrensNames;
+     ```
+6. Class and instance variables must be prefixed with an underscore (_) [mandatory].
+7. Variables must not be named using the so-called Hungarian notation [mandatory].
+   For example:
+    ```java
+    int nCount = 4; // not allowed
+    ```
+8. Only one variable may be defined per line [mandatory].
+9. Variable declarations should be indented 4 spaces more than their enclosing class [mandatory].
+10. All variables should be preceded by a javadoc comment that specifies what the variable
is for,
+    where it is used and so forth. The comment should be of the following form and be indented
+    to the same level as the variable it refers to [recommended]
+11. Never declare instance variables as public unless the class is effectively a "struct"
[mandatory].
+12. Never give a variable the same name as a variable in a superclass [mandatory].
+13. Ensure that all non-private class variables have sensible values even if no instances
have been created
+    (use static initialisers if necessary, i.e.`static { ... }`) [mandatory].
+    Rationale: prevents other objects accessing fields with undefined/unexpected values.
+
+#### Methods
+This section gives guidelines for class and instance method definitions in Java.
+In this section if a rule uses the term method rather than instance method or class method,
+then the rule applies to both types of method.
+
+1. Constructors and finalize methods should follow immediately after the variable declarations
[mandatory].
+2. Do not call non-final methods from constructors. This can lead to unexpected results when
the class is subclassed.
+   If you must call non-final methods from constructors, document this in the constructor's
javadoc [mandatory].
+   Note that private implies final.
+3. Methods that are associated with the same area of functionality should be physically close
to one another [recommended].
+4. After grouping by functionality, methods should be presented in the following order [recommended]:
+   * private, protected, public: static methods.
+   * private, protected, public: instance methods.
+    It should be noted that as javadoc will automatically order methods in a consistent manner,
+    rigid adherence to this rule is not necessary.
+5. Method modifiers should be presented in the following order: abstract, static, final.,
synchronized [mandatory]
 
 Review comment:
   Fixed
 
----------------------------------------------------------------
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:
users@infra.apache.org


> [Broker-J] Create a developer guide for Qpid Broker-J
> -----------------------------------------------------
>
>                 Key: QPID-8361
>                 URL: https://issues.apache.org/jira/browse/QPID-8361
>             Project: Qpid
>          Issue Type: Task
>          Components: Broker-J
>            Reporter: Alex Rudyy
>            Priority: Major
>             Fix For: qpid-java-broker-8.0.0
>
>
> The developer documentation is currently scattered over various Qpid confluence pages.
It could be challenging for people interested in contributing to the project to find that
documentation. A developer guide could be added to cover such aspects as
> * Environment Setup
> * Building project
> * Running tests
> * Releasing
> * Architecture overview
> The following wiki pages are good candidates for inclusion into a developer guide:
> [High Level Architecture|https://cwiki.apache.org/confluence/display/qpid/High+Level+Architecture]
> [How To Build Qpid Broker-J|https://cwiki.apache.org/confluence/display/qpid/How+To+Build+Qpid+Broker-J]
> [Releasing Qpid Broker-J|https://cwiki.apache.org/confluence/display/qpid/Releasing+Qpid+Broker-J]
> The wiki pages below might be included as well
> [Java Coding Standards|https://cwiki.apache.org/confluence/display/qpid/Java+Coding+Standards]
> [Qpid Java Run Scripts|https://cwiki.apache.org/confluence/display/qpid/Qpid+Java+Run+Scripts]
> The developer documentation should be easy to modify, maintain and preview. Thus, it
can be written in  markdown or [asciidoc|https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/].
The latter is also supported on github. 
> Potentially, it can be published on Qpid  project site as part of release process.



--
This message was sent by Atlassian Jira
(v8.3.2#803003)

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@qpid.apache.org
For additional commands, e-mail: dev-help@qpid.apache.org


Mime
View raw message