-
Notifications
You must be signed in to change notification settings - Fork 921
Add kiro steering docs #6280
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: master
Are you sure you want to change the base?
Add kiro steering docs #6280
Conversation
|
return fallbackData(); | ||
}, executor); | ||
``` | ||
- **Use appropriate completion methods**: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
what about whenComplete
? We use it a lot
- Include comprehensive Javadoc for public APIs | ||
- Keep methods short and focused on a single responsibility | ||
- Limit the number of method parameters (ideally 3 or fewer) | ||
- Use appropriate access modifiers (private, protected, public) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
will Kiro know what is "appropriate" or should we elaborate?
- 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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Does this section seems a bit restrictive? We don't want any other options?
``` | ||
- `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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
SDK ToString
utils for toString()
?
- `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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Should we provide guidance to use @nullable instead or just not doing it?
- All public POJO classes **MUST** implement `toString()`, `equals()`, and `hashCode()` methods | ||
- When adding new fields to existing POJO classes, these methods **MUST** be updated to include the new fields | ||
- Implementation guidelines: | ||
- `toString()`: Include class name and all fields with their values |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Possible additional guideline - do not include fields that could be considered sensitive such as credentials
``` | ||
- `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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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();
- 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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
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.