Author: jahewson
Date: Fri May 8 19:10:29 2015
New Revision: 1678428
URL: http://svn.apache.org/r1678428
Log:
PDFBOX-2672: Update coding conventions
Modified:
pdfbox/cmssite/trunk/content/codingconventions.mdtext
pdfbox/cmssite/trunk/templates/skeleton.html
Modified: pdfbox/cmssite/trunk/content/codingconventions.mdtext
URL:
http://svn.apache.org/viewvc/pdfbox/cmssite/trunk/content/codingconventions.mdtext?rev=1678428&r1=1678427&r2=1678428&view=diff
==============================================================================
--- pdfbox/cmssite/trunk/content/codingconventions.mdtext (original)
+++ pdfbox/cmssite/trunk/content/codingconventions.mdtext Fri May 8 19:10:29
2015
@@ -2,18 +2,92 @@ Title: Coding Conventions
# Coding Conventions
-## Introduction
+Over the years the PDFBox project has come to adopt a number of coding
conventions. These are not allways followed in old code but new code should try
to follow these rules where possible.
-To improve the readability and to ease maintenance of the PDFBox code there
are a small
-number of coding conventions.
+### Formatting
-### Indentation
+- Four spaces for indents, no tabs.
-Use 4 spaces for indentation. No tabs!
+- Braces go on their own line.
-### Brackets
+- Always use braces with control flow statements.
-Place open braces on the line after the declaration, for example:
+- No lines longer than 100 characters, including JavaDoc.
+
+ For wrapped lines, either use an indent of 4 or 8 characters or align with
the expression at the same level on the previous line.
+
+- Wrapped lines should be broken after operators, not before.
+
+- Prefer aligned wrapped lines.
+
+- Prefer aligned wrapped parameter lists.
+
+### Structure
+
+- Do not use package imports (e.g. `import java.util.*`)
+
+- Static fields and methods must appear at the top of a class, before any
other code.
+
+- Within a class, definitions should be ordered as follows:
+ - Class (static) variables
+ - Instance variables
+ - Constructors
+ - Methods
+
+### Whitespace
+
+- Do not use spaces around parenthesis.
+
+- Use spaces after control flow keywords.
+
+- Prefer using blank lines to separate logical blocks of code, but do not be
excessive.
+
+- Prefer not following casts with a blank space.
+
+
+### JavaDoc
+
+- Public and protected methods and fields must have JavaDoc.
+
+- Don't include @version tags or your e-mail address in JavaDoc.
+
+- Private methods do not require JavaDoc but may have partial JavaDoc if it
adds valuable information.
+
+## Comments
+
+- Only use line comments within code, never block comments.
+
+- Prefer comments on their own line, rather than trailing, unless the latter
is more readable.
+
+## Variables
+
+- Prefer initializing variables when they are declared, rather than C-style
declaration before use.
+
+- Always use final fields when possible.
+
+## Control Flow
+
+- Prefer multiple return statements over additional control flow logic.
+
+- Prefer switch statements over multi-clause if-then statements.
+
+## API Design
+
+- Give variables and methods meaningful names. Keep these short but don't use
abbreviations. Prefer using the same terminology as the PDF spec.
+
+- Prefer final classes and final protected methods for non-final public
classes, this reduces the surface area of the public API
+
+- Avoid non-final protected variables in public classes. Prefer protected
getters over protected variables when protected fields are necessery in public
classes.
+
+- Minimize the API. Don't make everything public just because you can.
+
+- Don't expose implementation details unless there is a clear need: allowing
subclassing means that the behaviour of protected methods becomes part of the
contract of the public AP
+
+- Avoid unnecesary abstraction. While you're encouraged to avoid brittle
designs, it's unlikey that an API designed for "future use" will have the
correct API without any code which actually uses it.
+
+## Example
+
+Here's an example of PDFBox's formatting style:
:::java
public class Foo extends Bar
@@ -27,47 +101,25 @@ Place open braces on the line after the
System.out.println(Integer.parseInt(args[i]));
}
}
- catch(NumberFormatException e)
+ catch (NumberFormatException e)
{
e.printStackTrace();
}
}
- }
-
-
-### Line Wrapping
-
-Wrap lines longer than 100 characters. For wrapped lines, either use an indent
of 8
-characters or align with the expression at the same level on the previous line.
-
-
-### Declarations
-
-Within a class or interface, definitions should be ordered as follows:
-
- - Class (static) variables
- - Instance variables
- - Constructors
- - Methods
-
-### Imports
-
-Do not use package imports (for example import import java.util.*;)
-
-### Other
+ }
-For other cases, we try to follow [Sun's code
conventions](http://java.sun.com/docs/codeconv) as much as possible.
+---
-## For Eclipse Users
+## Eclipse Formatter
-Eclipse users may download this preferences file: pdfbox-checkstyle-5.xml and
import this into Eclipse.
+Eclipse users may download this preferences file: pdfbox-eclipse-formatter.xml
and import this into Eclipse.
(Window->Preferences, go to Java->Code Style->Formatter and click "Import...").
Once you have done this you can reformat your code by using Source->Format
(Ctrl+Shift+F).
Also note that Eclipse will automatically format your import statements
appropriately when
you invoke Source -> Organize Imports (Ctrl+Shift+O).
-## Code analysis using SonarQube
+## SonarQube
The ASF hosts a SonarQube instance to automatically perform a code analysis of
apache projects.
PDFBox has its own [Sonar
instance](https://analysis.apache.org/dashboard/index/org.apache.pdfbox:pdfbox-reactor)
Modified: pdfbox/cmssite/trunk/templates/skeleton.html
URL:
http://svn.apache.org/viewvc/pdfbox/cmssite/trunk/templates/skeleton.html?rev=1678428&r1=1678427&r2=1678428&view=diff
==============================================================================
--- pdfbox/cmssite/trunk/templates/skeleton.html (original)
+++ pdfbox/cmssite/trunk/templates/skeleton.html Fri May 8 19:10:29 2015
@@ -135,8 +135,8 @@
</li>
<li class="sidebar-header">Development</li>
- <li><a href="/codingconventions.html">Coding
Conventions</a></li>
<li><a href="/building.html">Building from Source</a></li>
+ <li><a href="/codingconventions.html">Coding
Conventions</a></li>
<li><a href="/ideas.html">Ideas</a></li>
<li><a href="/references.html">External Links</a></li>
