The design addresses all the requirements as specified in the requirements documents and/or the forum.

The reviewer should be able to take each point in the requirements document and find the associated implementation in the design. The reviewer should read the component forum prior to doing this to ensure that any modifications or additions to the requirements are taken into account.

Rating 1 – The design is missing any of the ‘core’ requirements.

Rating 2 – The design has all of the ‘core’ requirements but does not address a majority of the ‘non-core’ requirements

Rating 3 – The design has all of the ‘core’ requirements and a majority of the ‘non-core’ requirements and, potentially, includes minor additional functionality.

Rating 4 – The design addresses all requirements and provides new and substantially useful (to the customer) functionality.

‘Core’ requirements are those requirements that are essential to component’s intent (i.e. the component either cannot fulfill its goal or cannot provide value added service to the customer without those requirements).

The component specification includes a clear and easily grasped explanation of any algorithms used in the design.

The reviewer should judge whether the algorithms are complete, accurate and contain enough information for the developer to properly implement. Please note that this review question should judge the correctness of the algorithm and how well the designer relates the algorithm – the grammar and spelling should NOT be included in this question.

Rating 1 – The component specification is missing a description for any of the algorithms used in the design or external research is required to understand how to implement any of the algorithms.

Rating 2 – The component specification includes all the algorithms. However, the description is hard to understand or contains errors, misunderstandings or is generally written in a style that is hard to understand – generally requiring many readings to fully grasp the algorithm. The developer may need external research to fully understand the algorithm.

Rating 3 – The component specification includes all the algorithms. The description is fairly clear with, at most, minor errors and includes everything needed by the developer to implement without any external research.

Rating 4 – The component specification includes all the algorithms. The description is clear, contains no errors and can be understood from a single reading.

The use cases cover all the business requirements as stated in the requirements document.

The reviewer should be able to take each requirement and find a use case covering that requirement (a single use case can cover more than one requirement). Care must be taken to ensure that the use cases are not too high-level or too low-level. If the designer included additional functionality beyond the requirements, that functionality must be covered by use cases also.

Rating 1 – A majority of the requirements are not covered by the use cases.

Rating 2 – A majority of the requirements are covered but some are missing and/or the use cases are too high (or low) level in detail.

Rating 3 – All the requirements are covered at a proper level of detail.

Rating 4 – All the requirements are covered at a proper level of detail and the designer made proper use of inherited/associations/extend/include semantics.

The sequence diagrams cover all the use cases.

The reviewer should be able to take each use case and find a sequence diagram that covers it. Please note that this question allows a cascade effect with the prior question – any missing use cases will likely have missing sequence diagrams as well.

Rating 1 – A majority of the use cases are not covered by the sequence diagrams or a majority of the use cases are missing.

Rating 2 – A minority of use cases are missing their sequence diagrams or a minority of use cases are missing.

Rating 3 – All the use cases are covered (and none were missing), however, a single sequence diagram covers multiple use cases.

Rating 4 – All the use cases are covered (and none were missing) and there is a one to one relationship between use cases and sequence diagrams.

The design incorporates standard design patterns and methodologies where applicable (e.g. Model-View-Controller, Factory Pattern, Object Oriented design principles, follows J2EE specs).

The reviewer should determine a few things: Are the patterns/methodologies used 'forced' (i.e. is there good justification for using the pattern or did the designer force the pattern into the design to say they used that pattern). Are the patterns/methodologies implemented correctly (this does not mean completely – the design may justify a partial implementation)? Did the designer show an understanding of the pattern/methodology? Did the designer recognize and document all the patterns used?

Rating 1 – A pattern/methodology was inappropriately used that could cause problems either in implementing the component or in implementing future enhancements to the component.

Rating 2 – An appropriate pattern/methodology was used but the designer showed a lack of understanding in the implementation of it. A pattern/methodology should have been used but was not or a pattern/methodology was 'forced'.

Rating 3 – Appropriate patterns and/or methodologies were used but the designer missed some in the component specification (either missed completely or incorrectly labeled).

Rating 4 – Appropriate patterns and/or methodologies were used and were identified correctly. The reviewer should also assign this rating if the design, appropriately, does not need any patterns/methodologies.

The design accounts for incorporating future enhancements and/or features beyond the requirements.

The reviewer should consider what enhancement/features the next version of the component will likely be or what types of enhancements a client of the component will likely request. The reviewer should then review the future enhancements that the designer included in the component specification for their vision of what the next likely enhancements are. The reviewer should also consider how tightly coupled the classes were or what assumptions the design was built upon when considering how ‘substantial’ the modifications would be.

Rating 1 – The design would need substantial modifications to accommodate the enhancements both the reviewer and designer came up with.

Rating 2 – The design could accommodate (without substantial changes) the enhancements the designer included but would need substantial changes to accommodate the reviewer enhancements.

Rating 3 – The design could accommodate (with moderate changes) both the reviewer and designer enhancements.

Rating 4 – The design could easily accommodate the reviewer and designer enhancements.

The component makes effective use of the TopCoder component catalog.

The reviewer should review the components recommended in the requirements documentation. The designer will need to provide justification (either in the component specification or in the component forum) if they choose not to use the recommendations. The reviewer should also review the TopCoder catalog for any components that could potentially be used in the component design. The reviewer should not be critical of the designer's use, assumptions or lack of details for components that are being proposed in the design or are currently in the design/development stage - as long as the designer has included verbiage in the component specification stating that the design may need to change based on the final 'look' of the dependent component. Please note that any components being proposed or changed by this design is dependent upon permission from the PM.

Rating 1 – The design did not use any of the recommended components and did not give sufficient justification as to why.

Rating 2 – The design used at least one of the recommended components but not all and did not give sufficient justification as to why. Likewise, assign this rating if the designer missed using likely components or used any other component incorrectly.

Rating 3 – The design used all the recommended components correctly but missed using other likely components.

Rating 4 – The design used all recommended and likely components correctly. Likewise, assign this rating if components were appropriately not used.

The component presents an easy-to-use API for the application to use.

The reviewer should look at the demo section of the component specification to see the designer's vision of how the component will be used. The reviewer should then analyze how the API addresses the requirements and how easy it is to use the API to accomplish the requirements.

Rating 1 – The API demonstrates an obvious lack of consistency, cohesion, or is generally hard to use. Tasks (as defined by the requirements) take multiple API calls to accomplish what should be done atomically.

Rating 2 – The API is not immediately obvious; one cannot understand how to accomplish the required tasks by looking at the class diagram and reading the demo section (provide the name(s) of the requirement task(s) not easily performed using the API).

Rating 3 – The API is obvious (by looking at the class diagram and the demo section) but could have been made simpler or more powerful/flexible (provide specific modifications to the API that would make it easier to use).

Rating 4 – The API is consistent, powerful, flexible, and is easy to understand. The design of the API is driven by a single concept, making the API easy to learn. The common tasks (as defined by the requirements) are easy to perform using the API.

The design addresses whether the component is thread safe or not.

The reviewer should review the component specification to see if the designer addresses the thread safety of the component. Please note that this does not mean the components must be thread safe – it simply means whether the designer has justified why it is or isn't thread safe. If the component is deemed thread safe, the designer should have documented their approach to thread safety in order to determine if the approach is sound. If the component is deemed not to be thread safe, the designer should document any reasons why the component is not thread safe.

Rating 1 – There is no mention of whether the component is thread safe or not.

Rating 2 – The designer mentions thread safety but fails to provide the reasoning

Rating 3 – The designer mentions thread safety but is incorrect in the reasoning

Rating 4 – The designer mentions thread safety and provides correct arguments to back it up.

The classes are well scoped.

The reviewer should determine whether the classes in the design attempt has too large of a scope (it tries to do too many tasks) or has too small of a scope (the task was broken down into too many classes). A good clue to a violation of this is whether the name of the class adequately encompasses the API of the class. If so, then the class is probably properly scoped (unless the name is too generic or too high-level).

Rating 1 – Multiple classes definitely violate scope and should be refactored into smaller or larger classes.

Rating 2 – A single class definitely violates scope and should be refactored into smaller or larger classes.

Rating 3 – The classes seem fine but at least one class could potentially benefit from being refactored.

Rating 4 – All classes seem to be scoped well.

Sub-packages have been defined to separate functionality into maintainable units.

The reviewer should make a determination whether classes in the design could be grouped into separate packages. This category generally applies to complex components or components that allow for functionality to be plugged in (where the functionality should justifiably exist in a separate package). Note: for pluggable components, the interface, implementations and any related abstract bases should be grouped within the package.

Rating 1 – The component is sufficiently complex or uses pluggable classes that can justifiably be separated into sub-packages and was not.

Rating 2 – The designer separated some classes into separate sub-packages but either missed some classes or missed other sub-packages that could be justified.

Rating 3 – The designer created an unnecessary sub-package or the component could potentially benefit from an additional sub-package (however this can not be justified).

Rating 4 – The designer appropriately used sub-packages or the design did not need any sub-packages.

Modifiers (final, abstract, synchronized, property, virtual, overrides, etc.) and scope (private, package, public, etc.) been appropriately used in the design in the classes/methods/variables.

Have internally used classes (to the component) been defined incorrectly as public? Has a public class improperly exposed protected or private members? Are abstract classes abstract? It is strongly advised that variables have a private scope (not even protected) and only be accessible via getter/setter methods (exception would be C#'s property variables). C# reviewers should note that Poseidon does not have the proper choices to fully represent the C# modifiers and therefore should not be marked down if the designer either uses the closest java modifier OR specifies it in the documentation tab. Additionally, the effect of the final, virtual and other similar modifiers on class extendibility should be considered in this question (rather than the future enhancements question).

Rating 1 – The designer demonstrates obvious lack of understanding. For example, by making everything public or by making something private that should be public.

Rating 2 – The design misidentifies a majority of the modifiers or scope.

Rating 3 – The designer misidentifies a minority of modifiers or scope.

Rating 4 – The designer identifies the modifiers/scope appropriately.

Custom exceptions been appropriately defined and do not cover multiple, unrelated reasons.

Has the designer appropriately reused existing system exceptions and appropriately defined custom exceptions for the rest? The reviewer should also imagine they were using this component in an application. If a custom exception is thrown, does it give enough information to the application to react appropriately? Example: an inappropriate custom exception would be some high level exception that is thrown for multiple, unrelated, reasons. Please note that TopCoder Software has decided that null arguments are represented by the null specific exception (NullPointerException and ArgumentNullException) and not the more generic IllegalArgumentException.

Rating 1 – Appropriate custom exceptions were not defined or a single generic exception is used throughout the component for every custom reason.

Rating 2 – Appropriate custom exceptions were defined but for multiple, unrelated reasons or system exceptions were reused inappropriately (this does not include the above null argument exception note).

Rating 3 – Custom exceptions were used appropriately for multiple, related reasons but do not give specific reason details beyond the included text or the design inappropriately identified a null argument exception.

Rating 4 – Custom exceptions were used appropriately and give reason details beyond simple text. Custom exceptions were used appropriately and for a single specific reason alone. Custom exceptions were not appropriate for this design.

Type assignments have been used appropriately for method arguments, variables and return types.

Are the type assignments correct and what you'd expect? Are the Collection interfaces used appropriately? If an actual array is used, is there justification why a Collection interface is not used? An issue to check for: if the return type is a Collection – make sure it's a clone (or similar) of the internal Collection to avoid exposing an internally protected field. Please note that TopCoder Software has made determination to prefer collection interfaces to arrays in all instances except where justified (presumably because of performance or overhead reasons and where either standard implementations or custom implementations would not provide the characteristics needed).

Rating 1 – Are a majority of types used incorrectly (not including array to collection stuff). That is, a string used where an integer should be etc.

Rating 2 – At least one type is used incorrectly (same limitation as Rating 1).

Rating 3 – The types are appropriate and arrays are used where collections should have been.

Rating 4 – The types are appropriate and the collection interfaces are used where appropriate (i.e. arrays are used when justified).

The relationships between classes within the component and between the component and external entities (other components, system classes) have been appropriately defined.

Are all relationships shown? Are the relationship attributes assigned appropriately (ordered, unordered, aggregate, composite, etc.)? Do they contain proper labels? Two ways of doing associations are appropriate:

1) Define a variable for the association, draw the association and label it with the variable.

2) Define the association and label it with a variable name – no variable needs to be shown for the relationship in the class.

Rating 1 – Relationships are missing between internal classes and/or external TopCoder components. Relationships are consistently missing attribute information.

Rating 2 – Relationships exist between internal classes and/or external TopCoder components. However, system classes are missing or some of the relationships have missing/incorrect attributes.

Rating 3 – Relationships between internal classes and external entities (both TopCoder components and system classes) have been defined. Some of the association attributes are either missing or incorrect.

Rating 4 – Relationships between internal classes and external entities (both TopCoder components and system classes) have been defined and all association attributes are correct.

The classes, methods and variables are named appropriately.

Does the name provide a hint as to what the function of the entity is? Does the name follow system language and TopCoder standards (capitalization, underscores, etc.)?

Rating 1 – The name of one or more entities is totally misleading or incorrect for the entity’s function. Note: the designer may challenge this if they can give sufficient justification as to why the name is appropriate. Only ‘public’ names should be eligible for this rating.

Rating 2 – One or more names violate either system language or TopCoder standards. Only ‘public’ names should be eligible for this rating.

Rating 3 – All names follow the system language and TopCoder standards, and the names cover the functionality of the entities; however another name may more fully describe the functionality. All names (private or public) are eligible for this rating.

Rating 4 – All names follow the system language and TopCoder standards and fully describe the functionality of the entity. All names (private or public) are eligible for this rating.

Please note that ‘public’ is defined as:

- Public or protected class names

- Public variables or protected variables on public or protected classes

- Public methods or protected methods on public or protected classes

The design made proper use of the language’s features.

Does the designer duplicate functionality that is already provided by the language? Are properties, delegates, interfaces, inheritance, networking, etc. used appropriately?

Rating 1 – Language features are consistently ignored.

Rating 2 – Language features are inconsistently ignored or consistently misused.

Rating 3 – Language features are incorporated consistently and occasionally misused or abused.

Rating 4 – Language features are used correctly.

The class documentation in the 'Documentation' tab of Poseidon provides a high-level description of the class, its role in the overall design and all relevant information to the developer.

The reviewer should look at this from a component developer standpoint and not an application developer standpoint. This is not javadoc on how to use the class. This should contain helpful information to the developer on how to develop the class and if the class is mutable or not.

Rating 1 – Documentation is consistently missing or consistently unhelpful.

Rating 2 – Documentation is missing in at least one class or consistently provides little help to the developer.

Rating 3 – Documentation is complete and adequate to develop the component but requires the designer to answer additional questions by the developer.

Rating 4 – Documentation is complete and provides full details to the developer (the developer will likely not require any additional information from the designer).

The method documentation in the 'Documentation' tab of Poseidon provides a detailed description of the method's scope, the parameters (including what is considered valid or not), return type (range, nulls, etc.) and any exceptions that may be thrown.

The reviewer should look at this from a component developer standpoint and not an application developer standpoint. This is not javadoc on how to use the method. This should contain helpful information to the developer on how to develop the method and what constraints the method will have. The designer does not have to provide physical examples of arguments. The designer does not have to explicitly say what is considered valid if this information is already contained in the documentation (whether it’s in the tags or in the free form text). The designer should not be required (nor even recommended) to duplicate the valid/invalid information and exception information in both the documentation tags and free form text if it’s clearly denoted in one or the other. However, it is recommended that complex validation (such as a regex pattern) be explained in only the free form text. Likewise, the reviewer should assume that any variable (null, empty string, int range, etc) is valid/invalid if not specifically denoted as an invalid/valid by the exceptions text or other free form information. Also note that the designer does not need to specify ‘raised signals’ in Poseidon if the exception has been clearly denoted in the documentation tags or free form text.

Rating 1 – Documentation is consistently missing or unhelpful.

Rating 2 – Documentation is missing in at least one method documentation or consistently provides little help to the developer.

Rating 3 – Documentation is complete and adequate to develop the component but requires the designer to answer additional questions by the developer.

Rating 4 – Documentation is complete and provides full details to the developer (the developer will likely not require any additional information from the designer).

The variable documentation in the 'Documentation' tab of Poseidon provides a detailed description of the variable's scope, intended usage and potential range of values.

The reviewer should look at this from a component developer standpoint and not an application developer standpoint. This is not javadoc on how to use the variable. This should contain helpful information to the developer on how to use the variable and what constraints (null, range, etc.) the variable will have. The designer should mention if the value is mutable, is set in the constructor and potentially where it will be modified and/or used. An initial value is not required unless appropriate for the variable (where it’s a constant or needs to be initially set to a certain value to ensure properly operation of the class [with proper documentation to denote why]).

Rating 1 – Documentation is consistently missing or unhelpful.

Rating 2 – Documentation is missing in at least one variable documentation or consistently provides little help to the developer.

Rating 3 – Documentation is complete and adequate to develop the component but requires the designer to answer additional questions by the developer.

Rating 4 – Documentation is complete and provides full details to the developer (the developer will likely not require any additional information from the designer).

The sequence diagrams provide sufficient detail for the developer to understand the interactions between classes.

The sequence diagrams should demonstrate to an adequate degree what interactions occur as a result of a method call.

Rating 1 – Sequence diagrams do not show sufficient details useful to a developer (e.g. they show the API call from the application but nothing beyond that).

Rating 2 – The sequence diagrams show some interaction but not enough to be able to develop from.

Rating 3 – The sequence diagrams show enough detail to give the developer an idea of what occurs on the method call.

Rating 4 – The sequence diagrams clearly show the detail of what occurs on the method call and potentially provides helpful notes on things that cannot be displayed visually in the diagram.

The component specification contains a comprehensive demo section.

Is the demo section complete (does it demonstrate each requirement)? Was it written in a way that 'promotes' the component (i.e. clear, demonstrates flexibility, etc.)?

Rating 1 – Demo section is missing or the existing demo section contains non-compilable errors (don't actually try to compile it – just view it to make sure it looks correct).

Rating 2 – The demo section demonstrates some but not all of the requirements or the demo section demonstrates class/methods/variables that don't exist in the design (probably were never updated).

Rating 3 – The demo section demonstrates each of the requirements correctly.

Rating 4 – The demo section demonstrates each of the requirements correctly in a clear fashion using a likely customer scenario (i.e. sets up a scenario that is similar to what a user of the component would see) or demonstrates extra functionality or flexibility.

The component specification contains no grammatical or spelling errors.

Was it written in a way that is easily understandable and doesn't require multiple readings to understand? This category should ONLY judge the grammar, sentence structure and spelling (i.e. the knowledge transfer piece). How well the designer explained the design structure or algorithms is addressed in a prior question.

Rating 1 – Useless. The document is not helpful to readers trying to understand or implement the component because of missing sections with critical information, frequent spelling errors, extremely poor grammar, etc.

Rating 2 - Marginally usable. The document provided some helpful information, but required multiple readings because of missing or incomplete sections, frequent spelling errors, unconventional wordings, poor grammar, etc.

Rating 3 – Usable. The document has no missing or incomplete sections, and provides enough helpful information to implement the component. The document requires significant efforts to read because the style is inconsistent, the material is not well organized, or there are occasional spelling or grammatical errors.

Rating 4 – Helpful. The document is well organized, easy to read, and stylistically consistent; it has no missing or incomplete sections, and no spelling errors. Despite an occasional unconventional wording or a few grammar mistakes, the document provides significant help to anyone trying to understand or implement the component.

The presentation of the diagrams and specification was professional.

Did the designer make use of fonts and colors to appropriately denote elements in the diagrams? Was the specification formatted in a professional looking manner? Was the diagram laid out in an easy to follow manner (most important elements in the top left to least important at the right and bottom edges)? Were like items grouped together (i.e. implementations [including the abstract base] of some interface should be near the interface)? Did the layout help you understand the design? Note: multiple class diagrams are allowed but discouraged unless separate sub-packages were used or the design was sufficiently complex that multiple diagrams help in the understanding.

Rating 1 – The presentation looks amateur. The presentation not only lacks the above elements but also actively confuses the reviewer in trying to understand the design.

Rating 2 – The presentation lacks many of the above but doesn't add to any confusion in understanding the design.

Rating 3 – The presentation looks professional but has some rough edges that can be improved upon.

Rating 4 – The presentation looks professional, and polished, and contributes to understanding the design.

Overall, this is a quality design that meets all requirements.

Please detail any additional comments regarding the component design.