[jira] [Comment Edited] (PDFBOX-2672) Wrong code convention link on the website

["John Hewson (JIRA)" <ji...@apache.org>]

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

John Hewson edited comment on PDFBOX-2672 at 2/7/15 7:52 PM:
-------------------------------------------------------------

Looking at the archived version of that page, it's not particularly readable and some of the conventions don't actually match what we use. I had a read through and I think we can reduce it more simply and include the rules which we actually follow. Here's a stating point:

- Four spaces for indents, no tabs.
- Braces go on their own line
- Always use braces with control flow statements
- No lines longer than 100 characters, including JavaDoc
- Wrapped lines should be broken after operators, not before
- Prefer aligned wrapped lines
- Prefer aligned wrapped parameter lists
- 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.
- Only use line comments within code, never block comments
- Prefer comments on their own line, rather than trailing, unless the latter is more readable
- 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
- Static fields and methods must appear at the top of a class, before any other code
- Prefer multiple return statements over additional control flow logic
- Prefer switch statements over multi-clause if-then statements
- Prefer initializing variables when they are declared, rather than C-style declaration before use
- Always use final fields when possible
- Prefer final classes and final protected methods for non-final public classes, this reduces the surface area of the public API
- 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 API

What do you think?


was (Author: jahewson):
Looking at the archived version of that page, it's not particularly readable and some of the conventions don't actually match what we use. I had a read through and I think we can reduce it more simply and include the rules which we actually follow. Here's a stating point:

- Four spaces for indents, no tabs.
- Braces go on their own line
- Always use braces with control flow statements
- No lines longer than 100 characters, including JavaDoc
- Wrapped lines should be broken after operators, not before
- Prefer aligned wrapped lines
- Prefer aligned wrapped parameter lists
- 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.
- Only use line comments within code, never block comments
- Prefer comments on their own line, rather than trailing, unless the latter is more readable
- 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
- Static fields and methods must appear at the top of a class, before any other code
- Prefer multiple return statements over additional control flow logic
- Prefer switch statements over multi-clause if-then statements
- Prefer initializing variables when they are declared, rather than C-style declaration before use
- Always use final fields when possible
- Prefer final classes and final protected methods for public classes, this reduces the surface area of the public API
- Don't expose implementation details unless their is a clear need: allowing subclassing means that the behaviour of protected methods becomes part of the contract of the public API

What do you think?

> Wrong code convention link on the website
> -----------------------------------------
>
>                 Key: PDFBOX-2672
>                 URL: https://issues.apache.org/jira/browse/PDFBOX-2672
>             Project: PDFBox
>          Issue Type: Bug
>          Components: Documentation
>            Reporter: Andrea Vacondio
>            Priority: Trivial
>
> Currently the website page https://pdfbox.apache.org/codingconventions.html points to the Sun's code convention -> http://java.sun.com/docs/codeconv but that page doesn't exist anymore. 



--
This message was sent by Atlassian JIRA
(v6.3.4#6332)

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