You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pdfbox.apache.org by ja...@apache.org on 2015/05/08 21:10:29 UTC
svn commit: r1678428 - in /pdfbox/cmssite/trunk:
content/codingconventions.mdtext templates/skeleton.html
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>