ViPER Guidelines
From ViPER Wiki
Contents |
[edit] Naming Conventions
Generally, the naming conventions defined by the Eclipse Project should be followed. They can be found here.
Addionally, the following naming conventions for projects should be followed:
- Plug-in projects should not contain any special suffix like (e.g. "-plugin). Only test plug-ins should be denoted with a special suffix, as specified below.
- Fragment projects should be named with a suffix "-fragment". However, the id of the fragment should not contain that suffix. For example, the ViPER logging fragment has the ID sc.viper.ide.logging while the project is named sc.viper.ide.logging-fragment.
- Feature projects should be named with a suffix "-feature". However, the id of the feature should not contain that suffix.
- Test plugins should end with a suffix ".tests", e.g. sc.viper.ide.tests. Test features containing the test plug-ins should end with ".tests-feature", e.g. sc.viper.ide.tests-feature
[edit] Style Conventions
[edit] Formatting
All ViPER projects have to use the ViPER specific code formatting standards!
You can set up your Eclipse/ViPER environment to automatically use the ViPER specific formatting setting as follows:
- Checkout the sc.viper.ide.releng project (if not already done). It contains a folder named configurationFiles, in which a code-formatter_ViPER_Profile.xml file is located that stores the ViPER specific Formatter profile.
- Go to Formatter preferences (Windows->Preferences->Java->CodeStyle->Formatter)
- Choose to import profile. Point to the code-formatter_ViPER_Profile.xml file.
[edit] Checkstyle (Eclipse-CS)
All ViPER projects have to conform to the ViPER specific Checkstyle guidelines!
You can set up your Eclipse/ViPER environment to locally check the ViPER specific Checkstyle constraints as follows:
- Install the Eclipse-CS plug-in via Update Manager from the Eclipse-CS update page (http://eclipse-cs.sourceforge.net/update).
- Checkout the sc.viper.ide.releng project (if not already done). It contains a folder named configurationFiles, in which a checkstyle_ViPER_Checks.xml file is located that stores the ViPER specific Checkstyle configuration.
- Import the ViPER specific Checkstyle configuration, therefore
- Go to Checkstyle preferences (Window->Preferences...->Checkstyle)
- Create a new Checkstyle configuration.
- Choose to import an existing external configuration file. Point to the checkstyle_ViPER_Checks.xml configuration file. Name the new Checkstyle configuration to "ViPER Checks". This is important, as all ViPER plug-ins are configured to expect a Checkstyle configuration with this name.
[edit] Logging
Logging should be based on Apache Commons Logging only! Logging statements like System.out.println, System.err.println, or e.printStackTrace() are not allowed, also no direct calls to other logging frameworks than Commons Logging (like e.g. Log4J)!
All plug-ins should only specify dependencies to the org.apache.commons.logging plug-in (as deployed by the org.eclipse.orbit) plugin.
No direct dependencies to org.apache.log4j should be made by any of the ViPER plug-ins (except those of ViPER MTF and ViPER UML2 CodeGen, which need to provide log appenders to retrieve OAW logging events, but do not use log4j for their own logging either).
Log4J is indeed used by the ViPER IDE for logging, but not visible to the ViPER plug-ins. The dependency to Log4J is provided by the sc.viper.ide-feature in form of a fragment (sc.viper.ide.logging) to the org.apache.commons.logging plug-in and is therefore not visible to any of the contained plug-ins.
Each class that needs to log should declare a private static final logger variable in the form (replace Activator.class with the class name of the respective class):
private static final Log logger = LogFactory.getLog(Activator.class);
Logging calls can then be made by calling the respective logging methods defined by the Logger class (which are similar to those of the Log4J Logger)
[edit] SCM Bug Integration
Bugzilla and CVS are integrated on dev.viper.sc using ScmBug.
Integration of CVS with Bugzilla ties the reason why a feature/defect was developed/fixed with what software changes occurred in CVS to accomplish this.
- To enable the integration the log message must optionally include one or more bug ids. Here are example log messages with bug ids:
bug 441:Something was done here.
bug 23,27,29: Several bugs can be given in the log message.
- Scmbug will verify that the CVS user issuing a commit is the assignee of the bug.
- It is possible to automatically change the resolution status of a bug at the time a software change is committed. It is verified that the requested resolution status is a valid resolution state in the bug-tracker and that the requested change does not violate the workflow of the bug-tracker. For example, changing a bug resolution in Bugzilla from REOPENED to UNCONFIRMED is an invalid status change. Changing resolution status is accomplished if a resolution template expected by Scmbug is identified in the log message. The resolution does not need to apply to the same bug the software change is applied against. It could be applied to a different bug, multiple bugs, or multiple different resolutions could be applied to multiple different bugs. Example log message that changes the resolution status of multiple bugs:
status 548,622: reopened status 755: resolved worksforme bug 547:Implemented automatic status resolution as a new policy. This seems to work but will need improvements in the testsuite. status 547: REsolved fIXED status 548: RESOLVED duplicate 547 status 647: assigned unassigned@mkgnu.net
[edit] Other conventions
- Never commit uncompilable code
- Classpath related rules
- Never reexport project-dependencies in the manifest
- Never specify dependent projects on build-path
