[UserStory] Documentation of the StarGenerator class needs to be more specific.

[ajhinds94]

User Story

Essential components

• [x] Title describes the story
• [x] Stakeholder type is identified
• [ ] Outcome is described
• [x] Rationale is explicit
• [ ] Acceptance criteria are verifiable and from the perspective of the stakeholder

Story

As a maintainer I want more accurate documentation of the StarGenerator.java class so that the functionality of the class is more clear.

Acceptance Criteria

_(Rules or scenarios are acceptable formats.)

• Rule 1 Documentation should state that it is a utility class.
• Rule 2 Should explain that the class generates a list of all possible patterns rather than districts.

Supporting Information

The class acts as a utility class, but this isn't explained anywhere within the documentation.

The documentation claims that it returns a list of "all possible districts", but the method is called generatePattern and only returns a nested ArrayList of patterns.

Dependencies

Dependents

129

Collaborators

@ajhinds94 , @sarahbarnes1994

[jody]

What part of the documentation of the class is "non-specific"?

There is no method in the class that has the intended behavior. Is that a weakness of the implementation of the class or an issue of the class documentation?

The method identified, generatePattern, doesn't in itself address the primary functionality of the class. However, it appears that it might be a utility used in accomplishing the objective of the class.

I agree with the Acceptance Criterion Rule 1, that it would be useful to explicitly state the term "utility". That said, I note that Java's standard utility classes don't do so (e.g., Arrays).

I'm not convinced that the Acceptance Criterion Rule 2 is appropriate. If the existing public method claimed to do something that it didn't, then I would agree. It may be that the class is just not yet fully implemented.

[ajhinds94]

So then, the issue we should be raising isn't so much that the documentation needs to be more specific/correct, but instead that the method itself isn't complete? I had assumed that the class was claiming to accomplish something that was actually happening elsewhere in the project.

[jody]

I had assumed that the class was claiming to accomplish something that was actually happening elsewhere in the project.

A good point! Is this accomplished somewhere else in the project? If so, then perhaps this entire class is unnecessary.

Alternatively, additional methods seem desired in the StarGenerator class. As a utility class, StarGenerator may house numerous useful methods that are invoked to perform specific behaviors (but not a constructor method).

[jody]

No response in over 30 days.