Skip to content

Commit 63ecd4d

Browse files
authored
Proposed changes for Domain Modeling guide (#2213)
Some minor editing for the Domain Modeling guide. - Removed the title here that probably got in by accident: https://cap.cloud.sap/docs/guides/domain-modeling#aspect-managed - Added some useful tip/warning titles
1 parent 2cd3bf1 commit 63ecd4d

File tree

1 file changed

+7
-8
lines changed

1 file changed

+7
-8
lines changed

guides/domain-modeling.md

Lines changed: 7 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -88,8 +88,7 @@ The more we succeeded in capturing intent over imperative implementations, the m
8888

8989
We use CDS as our ubiquitous modelling language, with CDS Aspects giving us the means to separate core domain aspects from generic aspects. CDS's human-readable nature fosters collaboration of developers and domain experts.
9090

91-
As CDS models are used to fuel generic providers — the database as well as application services — we ensure the models are applied in the implementation. And as coding is minimized we can more easily refine and revise our models, without having to refactor large boilerplate code based.
92-
91+
As CDS models are used to fuel generic providers — the database as well as application services — we ensure the models are applied in the implementation. And as coding is minimized we can more easily refine and revise our models, without having to refactor large boilerplate codebases.
9392

9493

9594

@@ -230,9 +229,9 @@ Note:
230229
- **Namespaces are optional** — use namespaces if your models might be reused in other projects; otherwise, you can go without namespaces.
231230
- The **reverse domain name** approach works well for choosing namespaces.
232231

233-
::: warning
232+
::: warning Avoid names that could change
234233

235-
Avoid short-lived ingredients in namespaces, or names in general, such as your current organization's name, or project code names.
234+
Don't use short-lived ingredients in namespaces, or names in general, such as your current organization's name, or project code names.
236235

237236
:::
238237

@@ -341,7 +340,7 @@ It is an unfortunate anti pattern to validate UUIDs, such as for compliance to [
341340

342341
On the same note, converting UUID values obtained as strings from the database into binary representations such as `java.lang.UUID`, only to render them back to strings in responses to HTTP requests, is useless overhead.
343342

344-
::: warning
343+
::: warning In summary:
345344

346345
* Avoid unnecessary assumptions, for example, about uppercase or lowercase
347346
* Avoid useless conversions, for example, from strings to binary and back
@@ -614,9 +613,9 @@ entity Books : NamedAspect { ... }
614613

615614
[Learn more about the usage of aspects in the _Aspect-oriented Modeling_ section.](../cds/aspects).{ .learn-more}
616615

617-
::: tip
616+
::: tip Consumers always see effective models
618617

619-
Consumers always see the merged effective models, with the separation into aspects fully transparent to them.
618+
The separation into aspects is fully transparent to consumers.
620619

621620
:::
622621

@@ -756,7 +755,7 @@ entity Books.texts {
756755

757756
Essentially, this is also what CAP generates behind the scenes, plus many more things to ease working with localized data and serving it out of the box.
758757

759-
::: tip
758+
::: tip `localized` keeps models comprehensible
760759
By generating `.texts` entities and associations behind the scenes, CAP's **out-of-the-box support** for `localized` data avoids polluting your models with doubled numbers of entities, and detrimental effects on comprehensibility.
761760
:::
762761

0 commit comments

Comments
 (0)