[[BackLinksMenu]]
[[PageOutline]]

'''IMPORTANT NOTE''': This document is being worked on. To see the latest approved version, go to [wiki:PLATFORM_STANDARDS_DESIGN?rev=17]. 

= How to make designs =
This document contains requirements and guidelines for writing good designs. Here you will find information about what a design should look like for the different kinds of tasks. Rules for reviewing will be provided as well. When doing the design you should not forget the major guideline of this project: '''Work towards the goal! '''

== Task kinds ==
The design should answer the quiestion how the task should be done. It should provide instructions about used technologies, algorithms, etc. Different task kinds have quite different requirements for the design, which are listed here:

=== Coding task ===
The design of these tasks should contain the following:
 * a list of all the classes that will be created (with descriptions and class diagrams)
  * note that a class/method that is not supposed to be inherited should be declared final.
 * links to all the classes that will be changed (this does not include the classes that will be refactored due to the changes introduced) and what will be changed in them (e.g. new methods will be added).
 * an explanation of what properties will be used
  * this is because the designs rely heavily on the properties library. The latter also means that generally the classes created should be ProObjects or immutable and that the ProObjects should contain only properties and static final fields.
 * Implementation methods, suggested algorithms, etc.
 * UML diagrams
 * Initial tests

There are subkinds of coding tasks with specific requirements for the design. These are:
 * '''External feature (visible from the user)''' - should 
 * '''Researching a technology or a library''' - should 
 * '''Internal feature (not directly visible)''' - should 
 * '''Structure changes (refactoring)''' - should 

=== Bug Fix ===
Design of bug fixes is similar to Coding tasks' design, but should also answer the questions  why does this bug appear, which part of the code is guilty for the wrong functionality (what was wrong with the code, why it was not suitable). Design also contains auto-tests that prove bug wouldn't be presented after implementation. These tasks should be designed by a developer.
  * In which module did the bug appear
  * In which part of the code did the bug appear
  * Required libraries
  * Implementation methods, suggested algorithms, etc.
  * UML diagrams (class diagrams) where needed
  * Initial tests

=== Document ===
Design should point which tools will be used, how the document will be created. Depending on specific task, these tasks may be designed by developer or qa.
  * Required auxiliary tools
  * Basic content of the document, a sentence for every fundamental thing. These will be expanded in Implementation section.
  * Useful external links
  * Image/Diagram requirements - content, file types, file sizes, position, etc.

=== Setup ===
Design  section should be decided which computer appliance will satisfy the requirements, how it will be set up, what technologies will be used. Give links to websites of software solutions that should be used. These tasks should be designed by a developer.
  * Hardware requirements - point specific hardware requirements, limitations if any.
  * Software requirements - point which of the suitable tools will be installed and configured.

=== Maintenance ===
Design explains what should be done for meeting the requirements, links to tools that will be used, algorithms, diagrams and whatever is needed for an easy implementation. Depending on specific task, these tasks may be designed by developer or qa.
  * If script are needed, design and link them
  * Link any used tools for maintaining appliances/files.
A good design doesn't leave any questions about implementation - when it's read, implementation should be trivial. Parts of the design may be pointed as implementation.
Use the design section [wiki:PageTemplates/TaskPageTemplate#Design] of the Task Page Template.

= Comments =
 * Perhaps it wont be bad to give a link to some good articles about TDD because it sounds frightening when it is first met. --pap@2009-01-15
 * Document's design should point the general layout structure of the documents. --pap@2009-01-15
 * Maintenance design should point which parts need maintaining. If it is aboud some documents then these would be the paragraphs and so on. --pap@2009-01-15
 * Setup design should link to tutorials that should be used for making the setup. --pap@2009-01-15
 * UML Diagrams and reqired libraries sound strange for a bugfix.  --pap@2009-01-15
 * Object construction methods are important so perhaps these could also be part of design standards. --pap@2009-01-15