Style guide
From BioclipseWiki
The following list of code style recommendations fills two purposes:
- Give the team of core developers a consensus standard coding style.
- Give those who care about code style/readability license to change the code of those who don't.
Due to the nature of this kind of bikeshedding, recommendations accompanied by a rationale are valued higher. Also, try to reach the author of a recommendation before adding a conflicting one. The mailing list or the discussion page are good places to do this.
Contents |
Lines
- Don't let lines in .java files exceed 80 characters.
- Code is easier to read if it fits in one screen, and 80 characters is historically the limit in terminal windows. There's a way to turn on a visual line marking the limit in Eclipse: Preferences… → General → Editors → Text Editors → Show print margin.
Indentation
- Use four-space indentation.
- It's the Eclipse standard anyway.
- Don't use tab characters for indentation (or anything else).
- Tabs show very differently in different editors. Traditionally, tabs usually denote (up to) eight spaces, not four, and all viewers abiding by this assumption will botch code with tabs in it. In Eclipse Preferences, Java → Code Style → Formatter → Edit… → Tab Policy = Spaces Only
There's a file tabless.xml in the bioclipse SVN repository that will automatically set the above two things for you. To import the coding style "Tabless conventions", go to Preferences > Java > Code Style > Formatter > Import... and select tabless.xml. Be warned that the conventions include many other stylistic tweaks besides the lack of tab characters. Lots of various whitespace stuff that aligns well with masak's coding style.
Blank lines
- Separate methods by a blank line.
- That way, methods are easier to tell apart.
- Code in paragraphs — insert blank lines between sets of statements that belong together.
- Once you start inserting blank lines in your code, you won't go back.
Braces
(Those that look like { and }, and which are used in Java to surround class/interface/method bodies, some if/while/try/for blocks and array initiations.
- Put the opening brace at the end of the line, not on its own line.
- This is the same as saying "Follow the BSD indentation style."
Commit messages
- Provide a commit message.
- There is a reason, however small, for every change made to the codebase. It will help the next person reviewing your code to know what that reason was.
- Explain why you made the change in the commit message, not only what was changed.
- Good commit messages function as a sort of glue providing verbal links between the things the commit changed, previous and future commits, the bug database, and the developer's plans.
- Be brief and topical.
- Commit messages are more useful the shorter they are. Provide the reasons for your commit and then stop. Don't document your code in commit messages. Don't talk directly to other developers via commit messages. Try to maximize the utility for the next person who looks at your commit message through the narrow lens of some svn utility.
