Update guidelins and add kiro steering docs #6280
Conversation
|
| return fallbackData(); | ||
| }, executor); | ||
| ``` | ||
| - **Use appropriate completion methods**: |
There was a problem hiding this comment.
what about whenComplete? We use it a lot
| - If the class does not implement `Supplier`: `{Noun}Provider` (e.g. `AwsCredentialsProvider`) | ||
| - If the "get" method has parameters: `{Noun}Factory` (e.g. `AwsJsonProtocolFactory`) | ||
|
|
||
| #### Service-specific classes |
There was a problem hiding this comment.
Does this section seems a bit restrictive? We don't want any other options?
There was a problem hiding this comment.
This is actually from the existing guideline
| - `Optional` **SHOULD** be used when it is not obvious to a caller whether a result will be null | ||
| - `Optional` **MUST NOT** be used for "getters" in generated service model classes | ||
| - For member variables: `Optional` **SHOULD NOT** be used | ||
| - For method parameters: `Optional` **MUST NOT** be used |
| ``` | ||
| - `equals()`: Compare all fields for equality, including proper null handling | ||
| - `hashCode()`: Include all fields in the hash code calculation | ||
| - Consider using IDE-generated implementations |
There was a problem hiding this comment.
Is this guidance useful for kiro? I think we often use the intelliJ auto-generated implementations, but not sure that will apply well here. I think the guidance maybe should be either: use java.util.Objects helpers or write explicit code.
There was a problem hiding this comment.
Removed this for now, will follow up in a separate PR
|
Should we add a mixed version compatibility guidance? |
| @@ -0,0 +1,133 @@ | |||
| --- | |||
| title: Asynchronous Programming Guidelines for AWS SDK v2 | |||
There was a problem hiding this comment.
Doesn't have to be in this PR but I think some guidance around locking and shared resources would be good too. For example w.r.t issues we had around making sure SdkUri/BoundedCache are performant
There was a problem hiding this comment.
Ack. We can follow up in a separate PR
| future.thenAccept(result -> processResult(result)); | ||
| ``` | ||
| - **Add stacktrace to exceptions**: When using `CompletableFuture#join`, use `CompletableFutureUtils#joinLikeSync` to preserve stacktraces | ||
| - **Don't ignore results**: Never ignore the result of a new `CompletionStage` if the parent stage can fail (unless you're absolutely sure it's safe to) |
There was a problem hiding this comment.
Might be good to add an example for this one, it might not be immediately apparent. e.g.
CountDownLatch latch = new CountDownLatch(1);
CompletableFuture<URL> future = new CompletableFuture<>();
future.thenRun(url -> {
downloadUrl(url);
latch.countDown();
});
latch.await();
.kiro/steering/testing-guidelines.md
Outdated
| - Avoid excessive stubbing - it can make tests brittle and hard to maintain | ||
| - [Wiremock](https://wiremock.org/) is commonly used to mock server responses in functional tests | ||
|
|
||
| ## Testing Asynchronous Code |
There was a problem hiding this comment.
Another useful method is sometimes we run hundreds/thousands of iterations of a test to ensure that none of the iterations fail, which is helpful for testing race conditions
There was a problem hiding this comment.
Ack. We can follow up in a separate PR
zoewangg
force-pushed
the
zoewang/kiroSteeringDocs
branch
2 times, most recently
from
039365b to
6144030
Compare
zoewangg
changed the title
zoewangg
force-pushed
the
zoewang/kiroSteeringDocs
branch
from
6144030 to
0200a0b
Compare
zoewangg
force-pushed
the
zoewang/kiroSteeringDocs
branch
from
0200a0b to
c60cd95
Compare
zoewangg
force-pushed
the
zoewang/kiroSteeringDocs
branch
from
c60cd95 to
4770230
Compare
|
github-merge-queue
bot
removed this pull request from the merge queue due to failed status checks
|
This pull request has been closed and the conversation has been locked. Comments on closed PRs are hard for our team to see. If you need more assistance, please open a new issue that references this one. |
Motivation and Context
Add kiro steering docs. I added existing guidelines from docs folder and internal docs. I also added additional guidelines that came to my mind.