Conversation
There was a problem hiding this comment.
This file is entirely human authored. It includes (with revisions) some text and concepts from prior design documents related to API design. I found that AI tools had little to add here.
|
|
||
| The above suggestions might not eliminate all optional parameters, or there might be other obstacles to removal. | ||
|
|
||
| ### Representing Optional Parameters |
There was a problem hiding this comment.
Numbering in this section (0.0 etc.), and specific categories, have been changed from prior documents.
There was a problem hiding this comment.
This file is based on the design doc, and is a heavily-directed AI analysis, with comments and human input. Claude (I think Opus) was very helpful in scanning for various patterns in the codebase, but it had trouble categorizing them into coherent sections. There was a lot of conceptual redundancy, and it failed to use suggested terminology and concepts on an initial pass. However, it was quite easy to correct this, and quickly produce major rewrites until the section was arranged as I expected.
| Concerns: | ||
| 1. Tracks the server API too closely, using static methods where chaining might have been possible. | ||
| 2. The upsert boolean might be moved into a new method name: `upsertOne`. | ||
| 3. [AI] The combine/merge operation has five different names across the static helper classes (see below). | ||
| 4. [AI] Options handling differs across helpers: Aggregates uses Options classes; Filters uses overloads and `@Nullable` parameters; Updates uses PushOptions only for `pushEach`. | ||
|
|
||
| **Static factory helper classes** (shared by both B1 and B2): Filters, Projections, Sorts, Updates, Indexes, Accumulators, Windows. Methods named after the operation: `Filters.eq()`, `Sorts.descending()`, `Updates.set()`. | ||
|
|
||
| Each helper class has a "combine" method, but they all use different names for it: |
There was a problem hiding this comment.
Concerns are generally directly human-authored, except where marked [AI]. Other text is AI-authored, based on an analysis of the codebase, with aforementioned guidance.
There was a problem hiding this comment.
Overall, this file is a good overview of the driver's public API, and I was surprised at the variety of patterns we used.
| @@ -0,0 +1,196 @@ | |||
|
|
|||
| This report is based on concepts discussed in api_design.md. The Part 1 is AI generated, Part 2 is human-authored. | |||
There was a problem hiding this comment.
This file is an experiment in how AI might be used to apply various principles to designing an idiomatic API. The whole of Part 1 is AI authored, without human guided revision.
I believe densify was the focus because it was used in examples earlier. I don't consider the redesign particularly successful, and I don't think we can rely on it to autonomously implement various builders, even with very explicit guidance.
But it is useful as a jumping-off point. I think it made it easier to articulate what I would have proposed, if we were considering redesigning densify (which we have no plans to do).
|
|
||
| Option C was rejected because it separates step from bounds, despite their tight interdependence. This widens the operation signature and makes the relationship between parameters implicit rather than structural. | ||
|
|
||
| # Part 2 (Human eval) |
There was a problem hiding this comment.
Below is entirely human-authored.
1 participant
JAVA-5251
Draft. This includes a couple of files that I don't expect to merge (api_eval, api_redesign_densify).
Rather than creating an internal doc, I propose to merge the api_design doc into the repository, akin to the specifications repo.