jspecify / jspecify/jspecify

Consider our stance on contractions

Open
#819 2 comments 0 reactions 0 assignees View on GitHub

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:

I also dug up a couple style guides:

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.