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