You can find this post in .docx version in
- Feature-incomplete designs with good documentation always win against feature-complete designs with poor documentation. This is because the ultimate goal of TopCoder software is to build a working component without involving the designer in the build process.
Use Case Diagram Tips:
Steps to design the use case:
- Design at least one use case for each requirement.
Exam your diagram for dependencies.
- Can you find use cases that depend on other use cases?
- Do you have groups of use cases that share functionality?
- Identifying and capture these associations (featuring dependencies, extensions, or inheritance) in a diagram will help you think about the classes in your design.
- Add comments as possible and never make assumptions that reviewer/developer will understand your design easily.
Class Diagram Tips:
- Pay attention to class scope and modifiers.
- Needs explanation “use stereotypes for language elements that you cannot model in UML”.
- For .NET designers, you need to model certain language features not generally available in UML (such as delegates) with classes.
- What’s meant by “navigability” in UML?
- Name your associations.
Member Variables Tips:
- Public data members are limited to constants.
Show variable’s initial value (if value coming from constructor ignore just notify for this <<constructor>>).
- Make sure to mention the initial value in the documentation panel.
- What’s meant by final variable?
Almost universally, your design should favor private variables with accessors over public variables.
- Static public final variables (which of course are not variables at all) represent the only exception.
- In general, reviewers will always catch your uses of non-static public variables, and score down your design.
- Public data members are limited to constants.
Methods and Constructors Tips:
- Include all public, protected and private methods and constructors in the model.
- Method modifiers play important role in conveying your intentions to the developers.
Sequence Diagram Tips:
- You need to create one sequence diagram for each non-abstract use case from your use case diagrams.
- Name your sequence diagrams the same way you named use cases.
- Make your sequence diagrams as detailed as possible.
- Use comments to clarify elements of your algorithm that you cannot put on a sequence diagram.
TopCoder uses a visual convention to show loops on sequence diagrams.
- See section on Templates and Samples for information on this and other visual conventions used at TopCoder.
Documenting Classes, Methods, and Variables Tips:
- Adding documentation is by picking “Documentation” tap related to the member.
Your documentation needs to explain two things:
- Why do you need this class, method, or variable? And
- How to implement it?
You need to explain the purpose this class or interface serves in the design.
- Is this a base class of a group of related classes?
- Do its methods provide an implementation of a particular algorithm?
- Does it participate in a design pattern?
- If you think it is helpful to the developers, mention it here.
You need to explain:
- The purpose of the method,
- Its parameters, and
- The exceptions it throws.
- Does your method implement a particular algorithm?
- Did you provide a sequence diagram for the method?
- Does the method check its arguments for validity? If it does not, why is it OK? What are the valid values of the method’s arguments?
- Does this method throw exceptions? When does it do it? If your method is non-trivial, consider providing pseudocode for it.
- What are valid values of each argument, and
- Say what happens when a value is outside its range (i.e. an exception is thrown, a log entry is added, a default value is used, or something else happens).
You need to explain:
- The purpose of the variable and a range of its legal values.
- When is the variable initialized?
- What is the initial value?
- For collections, provide types of values.
- For maps and dictionaries, provide types of their keys.
- Is the variable mutable?
- Do you need to synchronize access to this variable or use a synchronized or an unmodifiable collection?
- Provide all the relevant details in this section.
- Note that good documentation does not necessarily imply a lot of documentation: the amount of documentation you write should be commensurable with the complexity of the class or the method. Explain everything that may make the implementation easier. This makes the development easier, and translates into higher review scores.
Component Specification Document:
- The Component Specification document is intended to be a self-contained document describing your design. Ideally, a reader should understand high-level organization of your component from the Component Specification alone, without having to look at the diagrams.
Design Overview Section:
Answer the following questions:
- What is the primary purpose of the component?
- What are the most important pieces of the component’s functionality?
- How does the design address the requirements?
- What new functionality does the design add to the component?
- Note: Make this section short – the details go into the other sections of the document.
Describing the Required Algorithms Section:
- Giving developers a link or a book reference complete with a page number is acceptable.
- You should assume that developers are qualified coders with at least the elementary training.
- If your algorithm is not trivial, mention details about it.
- The best way to ensure that your algorithms work is to build a quick prototype and verify that the code you give to developers compiles, and does what you think it should do.
Documenting the design patterns Section:
- Mentioning design patterns by name and pairing them with classes in your design is sufficient for this section.
- Consequentially, the review board may score your submission lower for including unnecessary patterns that complicate the design.
Describing Configuration Requirements Section (I can’t understand what’s the hill required from this section!):
There are two approaches to making your design configurable:
- Provide a set of configuration APIs (I prefer this approach), or
- To use one or more configuration files.
- You need to discuss configuration only when you use configuration files.
Configuration API component in your design, the configuration section should provide answers to three questions:
- What namespace does your component use?
- What are the names of the properties that your component read?
- What are the example values of the configuration properties of your component?
- The template for the component specification contains a table where each configuration value must be documented, including it’s name, a description of what it will contain (including whether or not that particular value is required), and valid values for the configuration item.
Discussing Thread Safety Section:
- Answer the following:
- Is your component thread-safe or does it require external synchronization to be used in a multi-threaded environment?
- If your component is thread-safe, you should explain what makes it thread-safe. Typically, the discussion boils down to immutability and internal synchronization.
- What’s meant by internal synchronization?
Writing Good Demo Section:
This section is important for two reasons:
- It gives the reviewers and developers a chance to evaluate the simplicity of your component’s API.
- Helps other designers evaluate the applicability of your component to their own design.
- The requirements document gives you an idea of what to put in your demo section. Taking a scenario from the requirements and writing an implementation for it using the APIs of your component should be sufficient.
- Make sure to comment your demo section, and cover all features of your design.
- If your design can be extended in multiple ways, you should separate the “mainstream” uses from the extensions for the “advanced” users.
- Use the conventional wisdom and go from simple examples to more complex ones.
- Make your demo section easy to follow – it is your opportunity to present your component to the world, so use it to your advantage.
Wrapping Up and Submitting:
- How would you rate your submission on each of the questions in the scorecard?
- If you think that a certain item will not get a top rating, try fixing it if you have time.
- If you do not have enough time to address all items you think need more work, try fixing the documentation items first.
What’s extra to do:
- Read GoF.
- Read HF – OOD&A
- Read HF – DP
- Understand TopCoder UML tool from A-Z
- This is because we must remember every OO design principle and pattern in order to have professional competition not kofta one.