-
Notifications
You must be signed in to change notification settings - Fork 24
Developer guidelines
- Naming and conventions
- Source file structure
- Coding general rules
- Exceptions handling
-
Documentation
** Commit guidelines
** Commit messages guidelines - SWING guides and tutorial
- Use descriptive names for all variables, function names, constants, and other identifiers.
- Use single letter identifiers only for the counter in loops.
- Variable names start with lower case.
- Multi-word identifiers are internally capitalized.
- Do not use hyphens or underscores to separate multi-word identifiers.
To name constants use uppercase for each word and separate each pair of words with an underscore.
Define constants as static and final because "constants have contents which are deeply immutable and whose methods have no detectable side effects. This includes primitives, Strings, immutable types, and immutable collections of immutable types. If any of the instance's observable state can change, it is not a constant" [1].
Example: java static final String GENERIC_CONSTRAINTS_SYMBOLS
- Capitalize all letters in acronyms.
java int iPDANumber; //instead of iPdaNumber - For variable names use lowercase for the first word and capitalize only the first letter of each of the remaining words. * Use nouns as names for variables.
java protected float lowerValue
- Capitalize the first letter of each word that appears in a class or interface name.
java public class HlclProgram - Use nouns when naming classes
- Use nouns or adjectives when naming interfaces.
- For method names use lowercase for the first word and capitalize only the first letter of each of the remaining words.
- Use verbs as names for methods.
java public void parseDomain(String str, int precision)
[1] https://google.github.io/styleguide/javaguide.html#s3-source-file-structure
Java source code order
Each class should respect the following logical order.
- Instance variables declaration
- Constructors
- Own methods: following some logical order such as importance, use, reference between methods
- Getters and Setters
- toString, equals and clone methods, if they apply
Variable declaration
One variable per declaration
Every variable declaration (field or local) declares only one variable: declarations such as int a, b; are not used.
Local variables
Local variables should be declared close to the point they are first used (within reason), to minimize their scope. Local variable declarations typically have initializers, or are initialized immediately after declaration. Source code should not have unused local variables.
- All dependencies MUST be requested by the most generic type that is required by the client object. Ejm: List instead of ArrayList
- All non-public properties and methods SHOULD be private.
- There SHOULD be no circular dependencies between objects or modules
- All features or bug fixes must be tested (unit-tests).
- All public and protected methods must be documented.
- We follow the Java Style Guide. The most important guidelines were summarized here: source code standards
- UTF-8 encoding for Java sources
- Braces should be used with if, else, for, do and while statements, even when the body is empty or contains only a single statement.
*Braces will follow the Kernighan and Ritchie style ("Egyptian brackets") for nonempty blocks and block-like constructs:
// Generate the assigns for not ignored variables
for (String id : config.getNotIgnored()) {
// Create the atom
if (config.stateOf(id) == (int) config.stateOf(id)) {
org.jpl7.Integer i = new org.jpl7.Integer((int) config.stateOf(id));
Compound assign = new Compound("=", new Term[] { vars.get(id), i });
parts.add(assign);
} else {
org.jpl7.Float i = new org.jpl7.Float(config.stateOf(id));
// Create the compound for the assign.
Compound assign = new Compound("=", new Term[] { vars.get(id), i });
parts.add(assign);
}
}
Follow these nine best practices proposed by THORBEN JANSSEN to handle exceptions in java : 9 Best Practices to Handle Exceptions in Java Please, provide meaningful messages when throws exceptions in order to give enough details to final users or technical staff.
Hint: Use the shortcut Alt + shift+ j to generate a comment in the javadoc format of the method or class.
Class documentation Every class and method should be preceded with a descriptive comment using the "JavaDoc" notational convention. In the class, the comment should describe its purpose, and name the author.
/**
* Represents a logical exception from business logic functionalities
*
* @author Luisa Rincon - [email protected]
*
*/
public class FunctionalException extends Exception {}
Method documentation Comments should describe the method's purpose. Comment all arguments, the return value, and any exceptions using JavaDoc keywords. If you're documenting shared classes such as utility classes, also include your name. If the description is defined with multiple paragraphs, start each of them with
.
/**
* This methods splits text into different lines for easy of viewing
* @param str to format
* @param lineLenght: maximum number of characters
* @return formatted string with text separated into multiple lines
* @author Juan C. Muñoz Fernández <[email protected]>
*/
public static String multiLine(String str, int lineLenght) { }
Please read and follow the Commit Guidelines section of Pro Git. Key points are summarized below: Creates good commits makes working with Git and collaborating with others a lot easier.
- try to make each commit a logically separate changeset.
- if some of the changes modify the same file, try to use git add --patch to partially stage files
We follow Angular's message guidelines for formatting commit messages. Those rules are described here Angular commit messages guidelines
Each commit message consists of a header, a body and a footer. The header has a special format that includes a type, a scope and a subject:
The following example is adapted from: Commit template
# <header>
# <type>(<Project Prefix><ticket #>): use succinct description of the change:
#
# <body>
# Explain why this change needed to be made
# *use the imperative, present tense: "change" not "changed" nor "changes"
# *don't capitalize first letter
# *no dot (.) at the end
#
# <footer>
# Place to reference GitHub issues that this commit **Closes**. [closing reference to an issue](https://help.github.com/articles/closing-issues-via-commit-messages/) if any.
#
# ** TYPES **
# BUILD: Changes that affect the build system or external dependencies (example scopes: gradle)
# CI: Changes to our CI configuration files and scripts (example scopes: buildpaths, configuration files)
# DOCS: Documentation only changes
# NEWFUN: A new feature
# FIX: A bug fix
# PERF: A code change that improves performance
# REFACTOR: A code change that neither fixes a bug nor adds a feature. Put also the version number for this refactor
# STYLE: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
# TEST: Adding missing tests or correcting existing tests
#
# ** SCOPE**
# name of the module affected
# common
# HLCL
# solver
# dynsup
# gui
# IO
# reasoner
# Special cases
# changelog: used for updating the release notes in CHANGELOG.md
# doc: used for documenting VariMOs
# none/empty string: useful for `style`, `test` and `refactor` changes that are done across all packages (e.g. `style: add missing semicolons`)
#
# ** FOOTERS **
# References #1, #4, and #2.
# FIX #1. note this marks the item as accepted
# Closes #1 and #2. note this marks the item as accepted
The header is mandatory and the scope of the header is optional.
Any line of the commit message cannot be longer 100 characters! This allows the message to be easier
to read on GitHub as well as in various git tools.
Revert
If the commit reverts a previous commit, it should begin with revert: , followed by the header of the reverted commit. In the body it should say: This reverts commit <hash>., where the hash is the SHA of the commit being reverted.
Breaking Changes should start with the word BREAKING CHANGE: with a space or two newlines. The rest of the commit message is then used for this.
The following article presents a complete tutorial that covers the main concepts of creating User Interfaces with SWING