pdfbox-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jahew...@apache.org
Subject svn commit: r1678428 - in /pdfbox/cmssite/trunk: content/codingconventions.mdtext templates/skeleton.html
Date Fri, 08 May 2015 19:10:29 GMT
Author: jahewson
Date: Fri May  8 19:10:29 2015
New Revision: 1678428

URL: http://svn.apache.org/r1678428
PDFBOX-2672: Update coding conventions


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
+## 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
+- 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:
     public class Foo extends Bar
@@ -27,47 +101,25 @@ Place open braces on the line after the
-            catch(NumberFormatException e)
+            catch (NumberFormatException e)
-    }
-### 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 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>

View raw message