Skip to content

Commit 6de533f

Browse files
authored
chore: minor tweaks to DESIGN_GUIDELINES.md (#13073)
Was reading the Design Guidelines before contributing, and figured I'd improve it as I read through it ---- *By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*
1 parent f983fbb commit 6de533f

File tree

1 file changed

+9
-9
lines changed

1 file changed

+9
-9
lines changed

DESIGN_GUIDELINES.md

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ APIs and verifies that the APIs adhere to the guidelines. When a guideline is
1414
backed by a linter rule, the rule name will be referenced like this:
1515
_[awslint:resource-class-is-construct]_.
1616

17-
For the purpose of this document we will use "Foo" to denote the official name
17+
For the purpose of this document, we will use "Foo" to denote the official name
1818
of the resource as defined in the AWS CloudFormation resource specification
1919
(i.e. "Bucket", "Queue", "Topic", etc). This notation allows deriving names from
2020
the official name. For example, `FooProps` would be `BucketProps`, `TopicProps`,
@@ -98,8 +98,8 @@ or abstractions. However, you will notice that some sections explicitly call out
9898
guidelines that apply only to AWS resources (and in many cases
9999
enforced/implemented by the **Resource** base class).
100100

101-
AWS services are modeled around the concept of *resources*. Service normally
102-
expose through their APIs one or more resources, which can be provisioned
101+
AWS services are modeled around the concept of *resources*. Services normally
102+
expose one or more resources through their APIs, which can be provisioned
103103
through the APIs control plane or through AWS CloudFormation.
104104

105105
Every resource available in the AWS platform will have a corresponding resource
@@ -397,12 +397,12 @@ For example, prefer “readCapacity” versus “readCapacityUnits”.
397397
We prefer the terminology used by the official AWS service documentation over
398398
new terminology, even if you think it's not ideal. It helps users diagnose
399399
issues and map the mental model of the construct to the service APIs,
400-
documentation and examples. For example don't be tempted to change SQS's
400+
documentation and examples. For example, don't be tempted to change SQS's
401401
**dataKeyReusePeriod** with **keyRotation** because it will be hard for people
402402
to diagnose problems. They won't be able to just search for “sqs dataKeyReuse”
403403
and find topics on it.
404404

405-
> We can relax this guidelines when this is about generic terms (like
405+
> We can relax this guideline when this is about generic terms (like
406406
`httpStatus` instead of `statusCode`). The important semantics to preserve are
407407
for *service features*: I wouldn't want to rename "lambda layers" to "lambda
408408
dependencies" just because it makes more sense because then users won't be
@@ -697,8 +697,8 @@ _[awslint:from-signature]_:
697697
#### “from” Methods
698698
699699
Resource constructs should export static “from” methods for importing unowned
700-
resources given one more of its physical attributes such as ARN, name, etc. All
701-
constructs should have at least one "fromXxx" method _[awslint:from-method]_:
700+
resources given one or more of its physical attributes such as ARN, name, etc. All
701+
constructs should have at least one `fromXxx` method _[awslint:from-method]_:
702702
703703
```ts
704704
static fromFooArn(scope: Construct, id: string, bucketArn: string): IFoo;
@@ -870,7 +870,7 @@ vpcSubnetSelection?: ec2.SubnetSelection;
870870
871871
### Grants
872872
873-
Grants are one of the most powerful concept in the AWS Construct Library. They
873+
Grants are one of the most powerful concepts in the AWS Construct Library. They
874874
offer a higher level, intent-based, API for managing IAM permissions for AWS
875875
resources.
876876
@@ -974,7 +974,7 @@ class Function extends Resource implements IFunction {
974974
975975
### Events
976976
977-
Many AWS resource emit events to the CloudWatch event bus. Such resources should
977+
Many AWS resources emit events to the CloudWatch event bus. Such resources should
978978
have a set of “onXxx” methods available on their construct interface
979979
_[awslint:events-in-interface]_.
980980

0 commit comments

Comments
 (0)