wiki:PLATFORM_STANDARDS_DESIGN
Last modified 16 years ago Last modified on 01/26/09 14:43:59

Error: Macro BackLinksMenu(None) failed
compressed data is corrupt

  1. How to make designs
    1. General information
    2. Task kinds
      1. Coding task
        1. A sample approach
      2. Bug Fix
      3. Document
      4. Setup
      5. Maintenance
    3. Examples
    4. Reviewing
  2. Comments

IMPORTANT NOTE: This document has not yet passed the implementation phase. To see the latest approved version, go to PLATFORM_STANDARDS_DESIGN.

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.

General information

When doing a design you should not forget the major guideline of this project: Work towards the goal! Designs are written in the Design section of a task's wiki page. The design should answer the quiestion how the task should be done. It should follow the analysis and describe how every requirement can be achieved. A good design doesn't leave any questions about implementation - if it is well-written, implementation should be trivial. Parts of the design may be pointed as an implementation. It is very important that you understand the task very well before you try to design it because bad designs affect the whole project.

Task kinds

Different task kinds have quite different requirements for the design contents, which are listed here.

Coding task

The design of coding 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.
    • explanation of the objects construction methods should be provided
  • 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 either ProObjects or immutable and that the ProObjects should contain only properties and static final fields.
  • Implementation methods, suggested algorithms, etc.
  • UML diagrams
  • Initial tests/demos (or manual testing scenarios where applicable)
  • Links to any resources used for the design (especially when researching something)
  • A demo with some Dummy classes when designing a new library

A sample approach

When designing coding tasks, consider the following:

Bug Fix

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.

Document

The design of document tasks should state:

  • The outline of the document - a list of sections with brief description about their contents.
  • A desctipion of how the document will be created if it's a non-trivial one
  • If the document is a wiki page, you should include the PageOutline macro at the top.

Setup

The design of setup tasks should contain:

  • Technologies that will be used
  • Hardware requirements - point out if there are any limitations
  • Software requirements - point out what software will be deployed
  • Explanation of the setup process or links to tutorials about it

Maintenance

The design of maintenance tasks should contain:

  • A list of the things that will be maintained
  • Any scripts needed
  • Any tools that will be used

Examples

Please note that these examples have been created according to the previous version of the standards and do not fully reflect the new ones.

PLATFORM_DEPLOYMENT_BUILD_ECLIPSE_R1
PLUGIN_DECOMPOSITION_R2
S2S_PERSISTENCE_COMMONS_R0
SCS_REPO_MAINTENANCE_R2

Reviewing

The reviewer should track the presence of the following things:

  • Required things:
    • A note about every task requirement from the analysis section - should be one of the following:
      • a description of how it can be done
      • a motivated explanation of why it cannot be done
    • Presence of all the bullet-listed requirements for each task kind listed above
    • Clarity of expression - no misleading things that can be misunderstood or misinterpreted.
  • Recommended things:
    • Clear and consistent structure that is easily readable.

Reviewers should either follow the standards in this document or comment them in the Comments section of this page. If you state a task does not comply with the standards, point to the requirements that are not met. Scores are in the range 1-5. Here are the rules for scoring a design:

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

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.

Comments

Your comment here --developer-id@YYYY-MM-DD