|
|
|
dev:code_consistency [2009/11/25 08:00]
hjunes Links should have been internal. |
dev:code_consistency [2022/05/06 16:07]
|
| ====== 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 [[http://en.wikipedia.org/wiki/Database_normalization|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 | |
| |
| * [[dev:coding_style|Coding style]] | |
| * Helps to read and understand the code an to avoid errors (see also [[http://en.wikipedia.org/wiki/Programming_style|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 ==== | |
| |
| * [[http://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller#C.2B.2B|Model-View-Controller (MVC)]] | |
| * The 'model' parts are roughly concentrated in ''[[http://rosegarden.svn.sourceforge.net/viewvc/rosegarden/trunk/rosegarden/src/base/|src/base/]]'', in ''[[http://rosegarden.svn.sourceforge.net/viewvc/rosegarden/trunk/rosegarden/src/document/|src/document/]]'', and in ''[[http://rosegarden.svn.sourceforge.net/viewvc/rosegarden/trunk/rosegarden/src/command/|src/command/]]'' directories | |
| * The 'view' parts are roughly concentrated in ''[[http://rosegarden.svn.sourceforge.net/viewvc/rosegarden/trunk/rosegarden/src/gui/|src/gui/]]'' directory | |
| * The 'controller' parts are roughly concentrated in ''[[http://rosegarden.svn.sourceforge.net/viewvc/rosegarden/trunk/rosegarden/src/command/|src/command/]]'' and ''[[http://rosegarden.svn.sourceforge.net/viewvc/rosegarden/trunk/rosegarden/src/gui/|src/gui/]]'' directories | |
| * Each user-accessible action should fulfill individually the MVC pattern | |
| |
| ==== 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 [[http://en.wikipedia.org/wiki/Command_pattern|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 ==== | |
| |
| * [[http://en.wikipedia.org/wiki/Test_Driven_Development|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) | |
| |
| ==== 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 [[http://en.wikipedia.org/wiki/Moscow_Method|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. | |
| |
| ==== Data integrity ==== | |
| |
| * [[http://rosegarden.svn.sourceforge.net/viewvc/rosegarden/|Rosegarden repository]] has a non-standard "''trunk/rosegarden -- branches -- tags''" layout | |
| * [[http://svnbook.red-bean.com/en/1.1/ch05s04.html#svn-ch-5-sect-6.1|The repository layout recommended by Subversion]], our versioning system, is "''trunk -- branches -- tags''", with ''rosegarden'' removed after ''trunk/'' | |
| |
| * [[http://en.wikipedia.org/wiki/Dependency_hell|Dependency Hell]] | |
| * It is not easy to [[:frequently_asked_questions#what_about_windows_os-x_bsd|port Rosegarden to other OSs]], because of some OS-dependent [[dev:contributing#prepare_the_build_environment|build dependencies]] | |
| * Changes in the build dependencies are targeted to major releases. | |
| |
| ==== View ==== | |
| |
| * [[http://en.wikipedia.org/wiki/Magic_pushbutton|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 | |
| |
| * [[http://en.wikipedia.org/wiki/Interface_bloat|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 ==== | |
| |
| * [[http://en.wikipedia.org/wiki/Command_pattern|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 | |
| |
| ==== Methodology ==== | |
| |
| * [[http://en.wikipedia.org/wiki/Tester_Driven_Development|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 | |
| |
| ===== References ===== | |
| |
| * [[http://en.wikipedia.org/wiki/List_of_software_development_philosophies|List of software development philosophies]], Wikipedia | |
| * [[http://en.wikipedia.org/wiki/Design_pattern_%28computer_science%29|Design Patterns]], Wikipedia | |
| * [[http://en.wikipedia.org/wiki/Anti-pattern|Anti-pattern]], Wikipedia | |
| * [[http://www.lsd.ic.unicamp.br/~oliva/fun/prog/resign-patterns|Resign Patterns]], Michael Duell | |
