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.

Design patterns

The guide lines below are mostly justifiable

Data integrity

  • 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
  • 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

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

Controller

  • 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

Documentation

  • 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

Methodology

    • 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)

Releasing

  • 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)

Resign patterns

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.

Data integrity

View

  • 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

Controller

    • 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

Methodology

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

References

 
 
dev/code_consistency.txt · Last modified: 2022/05/06 16:07 (external edit)
Recent changes RSS feed Creative Commons License Valid XHTML 1.0 Valid CSS Driven by DokuWiki