Consider our stance on contractions
Nobody has claimed this yet.
- Dominant language
- Java
- Stars
- 1.1k
- Forks
- 43
- Avg merge
- 9m
- Merged PRs (30d)
- 13
Description
A comment by @wmdietl got me to do a survey of our current usage:
- https://jspecify.dev/docs/api/org/jspecify/annotations/NullUnmarked.html
- This annotation's purpose
- https://jspecify.dev/docs/api/org/jspecify/annotations/package-summary.html
- What's here
- it's important
- https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html
- MyOptional's type parameter
- MyList's type parameter
- they won't do that
- https://jspecify.dev/docs/api/org/jspecify/annotations/NullMarked.html
- it isn't necessarily
- It's non-null
- it's already the default
- https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html
- This doesn't guarantee
- won't produce an exception
- states can't be observed
- it's appropriate to overlook
- List's member signatures
I also dug up a couple style guides:
- https://developers.google.com/style/contractions
- https://learn.microsoft.com/en-us/style-guide/word-choice/use-contractions
I thought for a moment that Google at least didn't like "MyList's" and similar, given its critique of "browser's." But it goes on the clarify that it's talking about only the case "where 's means is." (So I guess that's "The browser's waiting for a response," or, in our world, "The List's null-hostile." So I think we're in the clear.)
I predict with 100% confidence that @kevinb9n is a fan of contractions in this context :)
It does strike me as mostly a question of formality: If we were to want to be very formal, then we'd want to avoid them; if we were to want to be very informal, then we'd want to use them. So we get to pick our point on that continuum.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Review the contraction examples in the linked NullUnmarked, package-summary, NonNull, NullMarked, and Nullable API documentation pages, then compare them with the linked Google and Microsoft style guides. Establish and record the project's preferred level of formality, and identify whether the documented examples should be revised consistently.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 38/100