SiyaoIsHiding commented on PR #2041:
URL:
https://github.com/apache/cassandra-java-driver/pull/2041#issuecomment-3465788694
I think realistically, no community contributor is gonna read 500+ lines
before they submit a single PR. It makes sense for the onboarding of a
full-time job, but it does not make sense for a community contributor, e.g.,
someone who maintains a library that uses the Java driver as a dependency and
only plans to create one pull request. When they open such a long file, even if
the file is nice and detailed, they are just gonna skip it.
If you agree ^ this is true, then we gotta make it shorter.
My 2 cents is that the following has lower priority and can be potentially
removed:
1. Examples to make a point stronger. E.g.
```
/**
* @return this {@link Builder} <-- completely unnecessary
*/
Builder withLimit(int limit) {
```
2. Things that users can easily find out by themselves. E.g.
> We use SLF4J; loggers are declared like this:
> private static final Logger LOG =
LoggerFactory.getLogger(TheEnclosingClass.class);
3. Things that are very general or common sense, nothing specific to this
Java driver project. E.g.
> Like commits, pull requests should be focused on a single, clearly stated
goal..
> If you have to address feedback, avoid rewriting the history (e.g.
squashing or amending commits): this makes the reviewers' job harder, because
they have to re-read the full diff and figure out where your new changes are.
4. Tips on a scenario that is unlikely to happen, and when it happens, we
can easily fix it in the PR review. E.g.
> Don't abuse the stream API
> The java.util.stream API is often used (abused?) as a "functional API for
collections"
It's rare that a community contributor submits a PR with this functional
stream API. And when it happens, we can fix it in the PR review. Such things
should be of low priority.
I think those points ^ are all good to have, but are less important than a
short CONTRIBUTING.md so that people actually read.
But if you both think the longer version is better, I will rewrite it. Pls
let me know what you think :)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
