| 23 | | There are subkinds of coding tasks with specific requirements for the design. These are: |
| 24 | | * '''External feature (visible from the user)''' - should |
| 25 | | * '''Researching a technology or a library''' - should |
| 26 | | * '''Internal feature (not directly visible)''' - should |
| 27 | | * '''Structure changes (refactoring)''' - should |
| | 28 | ==== A sample approach ==== |
| | 29 | When designing coding tasks, consider the following: |
| | 30 | * for UML diagrams: |
| | 31 | * A good place to get started with UML is http://www.uml.org/. There you will find all kinds of resources about it. |
| | 32 | * For the creation of diagrams we mostly use Visual Paradigm for UML (http://www.visual-paradigm.com/product/vpuml/) |
| | 33 | * for Auto tests: |
| | 34 | * Test Driven Development (TDD) is encouraged (and it is not as scary as it sounds). For more information, see the [http://en.wikipedia.org/wiki/Test-driven_development Wikipedia article] |
| | 35 | * For more information on writing auto tests, see [wiki:PLATFORM_STANDARDS_AUTO_TESTS]. |
| 30 | | 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. |
| 31 | | * In which module did the bug appear |
| 32 | | * In which part of the code did the bug appear |
| 33 | | * Required libraries |
| 34 | | * Implementation methods, suggested algorithms, etc. |
| 35 | | * UML diagrams (class diagrams) where needed |
| 36 | | * Initial tests |
| | 38 | The design of bug fixes differs a lot from other designs. Since most of the information about the bug is contained in the analysis section, the design is quite short. It should contain suggestions and ideas for fixing the bug or if the bug is more complicated it should follow the rules for the design of coding tasks. |
| 39 | | 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. |
| 40 | | * Required auxiliary tools |
| 41 | | * Basic content of the document, a sentence for every fundamental thing. These will be expanded in Implementation section. |
| 42 | | * Useful external links |
| 43 | | * Image/Diagram requirements - content, file types, file sizes, position, etc. |
| | 41 | The design of document tasks should state: |
| | 42 | * The outline of the document - a list of sections with brief description about their contents. |
| | 43 | * A desctipion of how the document will be created if it's a non-trivial one |
| 46 | | 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. |
| 47 | | * Hardware requirements - point specific hardware requirements, limitations if any. |
| 48 | | * Software requirements - point which of the suitable tools will be installed and configured. |
| | 46 | The design of setup tasks should contain: |
| | 47 | * Technologies that will be used |
| | 48 | * Hardware requirements - point out if there are any limitations |
| | 49 | * Software requirements - point out what software will be deployed |
| | 50 | * Explanation of the setup process or links to tutorials about it |
| 51 | | 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. |
| 52 | | * If script are needed, design and link them |
| 53 | | * Link any used tools for maintaining appliances/files. |
| 54 | | 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. |
| 55 | | Use the design section [wiki:PageTemplates/TaskPageTemplate#Design] of the Task Page Template. |
| | 53 | The design of maintenance tasks should contain: |
| | 54 | * A list of the things that will be maintained |
| | 55 | * Any scripts needed |
| | 56 | * Any tools that will be used |
| | 57 | |
| | 58 | == Examples == |
| | 59 | Please note that these examples have been created according to the previous version of the standards and do not fully reflect the new ones. |
| | 60 | |
| | 61 | [wiki:PLATFORM_DEPLOYMENT_BUILD_ECLIPSE_R1][[BR]] |
| | 62 | [wiki:PLUGIN_DECOMPOSITION_R2][[BR]] |
| | 63 | [wiki:S2S_PERSISTENCE_COMMONS_R0][[BR]] |
| | 64 | [wiki:SCS_REPO_MAINTENANCE_R2] |
| | 65 | |
| | 66 | == Reviewing == |
| | 67 | |
| | 68 | The reviewer should track the presence of the following things: |
| | 69 | * Required things: |
| | 70 | * A note about every task requirement from the analysis section - should be one of the following: |
| | 71 | * a description of how it can be done |
| | 72 | * a motivated explanation of why it cannot be done |
| | 73 | * Presence of all the bullet-listed requirements for each task kind listed above |
| | 74 | * Clarity of expression - no misleading things that can be misunderstood or misinterpreted. |
| | 75 | * Recommended things: |
| | 76 | * Clear and consistent structure that is easily readable. |
| | 77 | |
| | 78 | Reviewers should either follow the standards in this document or comment them in the ''Comments'' section of this page. Scores are in the range 1-5. Here are the rules for scoring a design: |
| | 79 | * Score 1 (fail): The design is not structured according to the standards (or is to very little extent) and/or there are a lot of things missing. |
| | 80 | * Score 2 (fail): The design is structured according to the standards in the most part but has some things that are missing (e.g. unit tests, diagrams), unclear or may mislead the implementer. |
| | 81 | * Score 3 (pass): The design is structured according to the standards but is too short and there's a lot more to be added or the diagrams are chaotic and unclear or the tests provided are insufficient. |
| | 82 | * Score 4 (pass): The design is structured according to the standards and provides enough information for the designer and implementer (clear diagrams, good tests, etc.). |
| | 83 | * Score 5 (pass): The design is structured according to the standards and there's nothing more to be added - it's perfect in such a way that a person who is not quite familiar with the project can do the implementation. |
| | 84 | |
| | 85 | All reviews should be motivated. A detailed comment about why a design fails is required. For a score of 3 a list of things that should be improved has to be provided. Comments are encouraged for higher scores as well. Non-integer scores are STRONGLY disencouraged. If you give a design a score of 3.5, then you probably have not reviewed it thoroughly enough and cannot clearly state whether it is good or not. Once a design has been reviewed, it cannot be altered. If you think it is wrong, you should request a super review. Currently all super reviews should be discussed with Milo. Make sure you are able to provide clear arguments of why the design is not good before you request a super review. |
| 58 | | * 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 |
| 59 | | * Document's design should point the general layout structure of the documents. --pap@2009-01-15 |
| 60 | | * 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 |
| 61 | | * Setup design should link to tutorials that should be used for making the setup. --pap@2009-01-15 |
| 62 | | * UML Diagrams and reqired libraries sound strange for a bugfix. --pap@2009-01-15 |
| 63 | | * Object construction methods are important so perhaps these could also be part of design standards. --pap@2009-01-15 |
| | 88 | ^Your comment here --developer-id@YYYY-MM-DD |
