JavaExercism/POLICIES.md

Track Policies

This document:

• describes all current track-wide policies; and
• lists all policies that should be reviewed in response to any given track event.

Maintainers should refer to this document each time they review a pull request.

Our policies are not set-in-stone. They represent directions chosen at a point in time with the information/context available at that time. We actively encourage contributors to review and critique them. If you have read through the references that informed an existing policy and still feel it should be improved or removed, please comment and describe:

1. your alternative perspective;
2. your proposed changes; and
3. how your proposal balances your own perspective with those already raised during prior discussions.

Event Checklist

Track Event	Policies to review
Exercise added	Prefer instance methods; Starter implementations; Ignore noninitial tests
Exercise updated	Ignore noninitial tests; Multiple file submissions
Track order changed	Starter implementations; Multiple file submissions
New issue observed in track	Good first patches
"Good first patch" issue completed	Good first patches
Installing Java instructions updated	Simple onboarding

Policy Descriptions

Prefer instance methods

Most (all?) exercises should be implemented in the form of instance methods since they contain "domain logic" and we (Exercism) want to encourage exemplary software.

References: [1]

Starter implementations

• Exercises 1-20: provide stubs for all required constructors and methods. Stubs should include the following body: throw new UnsupportedOperationException("Delete this statement and write your own implementation.");
• Exercises 21+: provide no stubs by default, but either (1) add hints to the HINTS.md file (which gets merged into the README.md for the exercise) or (2) provide stubs as in exercises 1-20 for exercises that demand complicated method signatures.

References: [1], [2]

Minimize initial complexity in user-facing code

Minimize (within reason) the number of Java language constructs a user is exposed to simultaneously at the beginning of the track. Instead, introduce those constructs with examples and hints in an appropriate later exercise. Specific applications of this policy include:

• avoiding use of the public keyword in user-facing class declarations, method signatures, and parameter signatures;
• avoiding use of the final keyword in user-facing class declarations, method signatures, and parameter signatures.

Ignore noninitial tests

All but the first test in an exercise test suite should add @Ignore("Remove to run test") (single test) or @Ignore("Remove to run tests") (parametrized test) on the line before the corresponding @Test annotation.

References: [1]

Multiple file submissions

The first exercise in the track whose test suite mandates multiple solution files should be accompanied by a HINTS.md file reminding the practitioner that the CLI supports multiple file submissions.

References: [1]

Good first patches

Aim to keep 10-20 small and straightforward issues open at eny given time. Identify any such issues by applying the "Good first patch" label. You can view the current list of these issues here.

References: [1]

Simple onboarding

The Installing Java instructions should seek to minimize the number of steps and the number of concepts a new-to-the-track practitioner needs to learn to get to coding.

References: [1]