Code consistency

We try to maintain code consistency with several methods. Some of the methods are very general while the others are specific only to the Rosegarden project.

A note on this page: this page is ment to be incomplete and subject to change.

The guide lines below are mostly justifiable

• Normalized code (compare Database normalization)
  • Data should exists at least once in the source tree
    • We try to check during compiling that the source files exist in the svn tree
  • Context-independent data should exists, preferably, at most once in the source tree
    • Context independent data definitions are typically in own libraries
    • Context dependent data, like similar function definitions in different contexts, are often repeated
    • Note: Removing duplicate data definitions is mostly manual work and may require a profound insight

• Coding style
  • Helps to read and understand the code an to avoid errors (see also Programming style in Wikipedia)

• Compilability
  • Stable branch should be always compilable
  • If no major restructuring of the code is going on, try to keep also the development branch always compilable
  • Commits which break the compilability of the code are highly preferred in branches

• Model-View-Controller (MVC)
  • The 'model' parts are roughly concentrated in src/base/, in src/document/, and in src/command/ directories
  • The 'view' parts are roughly concentrated in src/gui/ directory
  • The 'controller' parts are roughly concentrated in src/command/ and src/gui/ directories
  • Each user-accessible action should fulfill individually the MVC pattern

• Actions should be visible to the user
  • Every user accessible action should have a menu entry or a button with a tooltip

• Every document manipulating action should fulfill the Command pattern in order to be undoable
  • Same intention documented earlier in wiki page Manipulating the document
  • See also Commando pattern below in Resign patterns

• Minimalistic, up-to-date documentation in the source tree
  • menu entry serves as the documentation of an action
  • tooltip is used for a button action which is not documented in the menus
  • full documentation is hard to keep up-to-date — it has been moved to the wiki pages

• Test Driven Development
  • A single developer is typically also the tester of their own code
  • We often like to work also in short development cycles where the contributions of a single developer take temporarily the focus of many, nearly all active developers
  • The period between hard freeze and release is devoted for testing and bug-fixing (and translating)

• Predefined major and minor version numbering: {two-digit year}.{two-digit month}.{minor version}
  • Major version release does not have a minor number, e.g., 10.02
  • Bug release for a major version release toggles on the minor version, e.g., 10.02.1

• Debated code names ( unlike the version numbering, we like to debate about code names! )
  • Development code name may differ from the name of the actual major version release

• Single release dictator ( D. Michael McIntyre )
  • soft freeze: Decides the moment of calling for translators
  • hard freeze: Decides when only stabilizing work is accepted to the trunk, this is also the final call for translators
  • release: Decides when to release a major release
  • reinitiate: Branches a new stable branch from the trunk in order to make trunk/ again as the development branch
  • rerelease: Decides when or whether a major release deserves a bug fix release, new translations are automatically accepted to a rerelease

• Release early, release often, which means that
  • a new major release both introduces new features and fixes old bugs,
  • a new minor release fixes old bugs and may introduce new features,
  • the existence of earlier bugs is not an obstacle for a release, especially, if the release does not break functions which used to work in the previous release, and
  • release may introduce bugs into new features
  • see also MoSCoW method (Must / Should / Could / Would like to have)

These design choices typically do not follow the standard. In most of the time, we can live with that. There might appear changes to these choises in future. The reason for the list of resign patterns is that Code smell can be a driver for refactoring.

• Rosegarden repository has a non-standard “trunk/rosegarden – branches – tags” layout
  • The repository layout recommended by Subversion, our versioning system, is “trunk – branches – tags”, with rosegarden removed after trunk/

• Dependency Hell
  • It is not easy to port Rosegarden to other OSs, because of some OS-dependent build dependencies
  • Changes to these build dependencies are targeted to major releases

• Magic pushbutton anti-pattern
  • In some of our user-accessible actions a necessary level of abstraction is missing — instead of a the full MVC-model for the action, the 'model' has been put to the 'view' part
  • Missing abstraction, i.e., 'model' part, makes it harder to make changes to the user interface

• Interface bloat anti-pattern
  • Our user interface probably contains some functions which actually have been never used
  • The implementation and maintenance of the unnecessary functions may have driven the focus out of the bullet-proof implementation of the functions which are used the most

• Commando resign pattern
  • Every command which manipulates the document do not fulfill the Command pattern properly, thus, in some cases “undo” is broken
  • If the command is valuable, then we still prefer to “do” even if “undo” of the same command will be broken

• Tester driven development anti-pattern
  • We have had situation where the reaction to (old) bugs report got unnecessarily big focus over redesigning some more important parts

• List of software development philosophies, Wikipedia
• Design Patterns, Wikipedia
• Anti-pattern, Wikipedia
• Resign Patterns, Michael Duell