[UserStory] Documentation of StarGenerator.generatePattern needs to be more descriptive

[esundbla]

User Story

Essential components

• [x] Title describes the story
• [x] Stakeholder type is identified
• [x] 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 descriptive documentation for the method generatePattern in the StarGenerator Class
so that the API is more understandable and thus easier to use and maintain.

Acceptance Criteria

(Rules or scenarios are acceptable formats.)

• Consistent naming conventions in documentation and code

Supporting Information

Pattern and district are used interchangeably. One term should be used consistently documentation

Dependencies:

Dependents:

• 129

[jody]

(I made minor modifications to the wording of the issue for clarity and simplification.)

The Acceptance Criteria given in this issue doesn't appear to be violated by the code or documentation. The naming conventions specified for the project are articulated in the resources found in the Coding Convention Guide. They boil down to the Java naming conventions, none of which appear to be violated in the class or they would be reported by the Checkstyle target build.

It's unclear whether the issue is that the documentation is incorrect or simply insufficient.

In particular, the API of the specified method, ArrayList<ArrayList>StarGenerator.generatePattern(int), clearly indicates that the method does not return a collection of District objects.

It does return an ordered collection of ordered collections of Locations. Although the use of the term "pattern" is unusual and undefined, "pattern" does not appear to be used interchangeably with "district".

Please review and comment.

[esundbla]

Wording changes were helpful thank you.

The new Acceptance criteria would be a better definition of the term pattern. Its unclear from description what the method will return. Clear definition of pattern, and how origin(0,0) relates to said pattern!

Supporting information should change to reflect undefined term pattern.

[jody]

Thanks for the info!

It seems that we don't have a way of measuring "more descriptive" so we don't know how to know whether or not a proposed solution satisfies this User Story. That said, we now know some specific weaknesses; namely: the lacks of a definition of "pattern" and the meaning of "originate from".

[jody]

Still missing meaningful acceptance criteria. No response in over 30 days.