From 7c608faadf5cd2f5adbd5e881e8477b9676d3098 Mon Sep 17 00:00:00 2001 From: vjohnslhm <145964798+vjohnslhm@users.noreply.github.com> Date: Mon, 23 Sep 2024 17:31:32 +0200 Subject: [PATCH 1/4] #414 add docu for test naming conventions --- docs/.vitepress/config.mts | 3 + docs/src/technik/coding_conventions/index.md | 5 ++ .../coding_conventions/tests_naming.md | 62 +++++++++++++++++++ 3 files changed, 70 insertions(+) create mode 100644 docs/src/technik/coding_conventions/index.md create mode 100644 docs/src/technik/coding_conventions/tests_naming.md diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 34a57efd5..0cf64518b 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -32,6 +32,9 @@ export default withMermaid({ text: 'Getting Started', link: `${PATH_TECHNIK}get_started/` }, {text: 'Entwicklungsumgebung', link: `${PATH_TECHNIK}development/`}, + {text: 'Coding Conventions', link: `${PATH_TECHNIK}coding_conventions/`, collapsed: true, items: [ + {text: 'Naming Convention - Testing', link: `${PATH_TECHNIK}coding_conventions/tests_naming`} + ]}, { text: 'Adr', link: `${PATH_TECHNIK}adr/`, collapsed: true, items: [ {text: 'Renovate - ignoriere lombok', link: `${PATH_TECHNIK}adr/adr001-renovate-ignore-lombok`}, diff --git a/docs/src/technik/coding_conventions/index.md b/docs/src/technik/coding_conventions/index.md new file mode 100644 index 000000000..03b433d2d --- /dev/null +++ b/docs/src/technik/coding_conventions/index.md @@ -0,0 +1,5 @@ +# Coding Conventions + +Der Einsatz von Coding Conventions erhöht die Lesbarkeit und Struktur unseres Codes. + +Entscheidungen bezüglich der eingesetzten Conventions und wie diese konkret im Projekt umgesetzt werden, sollen hier dokumentiert werden. \ No newline at end of file diff --git a/docs/src/technik/coding_conventions/tests_naming.md b/docs/src/technik/coding_conventions/tests_naming.md new file mode 100644 index 000000000..eb5690071 --- /dev/null +++ b/docs/src/technik/coding_conventions/tests_naming.md @@ -0,0 +1,62 @@ +# Naming Convention für Tests + +## Kontext + +Damit der Code übersichtlicher und einheitlicher ist, sollen Naming Conventions eingesetzt werden. Damit wird für Tests gewährleistet, dass deren Inhalt klar ist, ohne den Code lesen zu müssen. + +## Entscheidung + +Die Bezeichnungen sollen dem Schema `should__when_` folgen, wobei Result (= ExpectedBehavior, bzw. erwartetes Ergebnis) und Input (= StateUnderTest, bzw. zu testender Zustand) in CamelCase gehalten werden. Dem Schema entsprechend sind die Testnamen auch auf englisch zu formulieren. + +Wir haben uns darauf geeinigt, die zu testenden Methoden mit `@Nested` zu gruppieren. Im Fall von überladenen Methoden werden diese innerhalb der Methodenklasse zusätzlich verschachtelt und ebenfalls mit `@Nested` annotiert. + +### Beispiele + +```java +// should_expectedResultInCamelCase_when_inputInCamelCase() {} +void should_returnDTO_when_givenValidId() {} +void should_notThrowException_when_newDataSaved() {} +void should_throwAccessDeniedException_whenAuthoritiesMissing() {} +``` + +##### Gruppierung überladener Methoden: +Vereinfachter Pseudocode! Beispiel aus Vorfälle und Vorkommnisse Service +```java +@Mapper +public interface EreignisModelMapper { + + Ereignis toEntity(EreignisModel model); + + List toEntity(EreignisseWriteModel model); +} +``` + +```java +class EreignisModelMapperTest { + @Nested + class ToEntity { // Name der zu testenden Methode + + @Nested + class ToEreignisEntity { // nested overload 1 + @Test + void should_returnEreignis_when_givenEreignisModel() {} + } + + @Nested + class ToListOfEreignisEntity { // nested overload 2 + @Test + void should_returnListOfEreignis_when_givenEreignisseWriteModel() {} + } + } +} +``` + +## Konsequenzen + +### positiv + +Durch die Einführung dieser Naming Conventions wird die Lesbarkeit und Verständlichkeit unserer Tests verbessert. Die einheitliche Namensgebung erleichtert es anderen Entwicklern, den Code zu verstehen und zu warten. Außerdem wird die Zusammenarbeit innerhalb des Teams effizienter, da jeder bei Bedarf schnell die relevanten Tests finden und bearbeiten kann. Darüber hinaus ermöglicht die Verwendung von `@Nested` eine bessere Strukturierung der Tests und eine einfachere Überprüfung der Testergebnisse. Insgesamt erwarten wir eine höhere Codequalität und eine schnellere Fehlererkennung durch die Einführung dieser Convention. + +### negativ + +Gegebenenfalls müssen - neben der Anpassung der Namen - einige bestehende Tests umgeschrieben werden, um der neuen Bezeichnung zu entsprechen. \ No newline at end of file From f882ea7b4be62acc6f5565ffa7d11748e8a04d67 Mon Sep 17 00:00:00 2001 From: vjohnslhm <145964798+vjohnslhm@users.noreply.github.com> Date: Tue, 24 Sep 2024 14:21:12 +0200 Subject: [PATCH 2/4] #414 :art: --- docs/.vitepress/config.mts | 5 +++-- docs/src/technik/coding_conventions/tests_naming.md | 8 ++++---- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 0cf64518b..65e9d4a1b 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -1,6 +1,7 @@ import {withMermaid} from "vitepress-plugin-mermaid" const PATH_TECHNIK = '/technik/'; +const PATH_CODING_CONVENTIONS = PATH_TECHNIK + 'coding_conventions/'; const PATH_FEATURES = '/features/'; const PATH_GUIDES = '/guides/'; @@ -32,8 +33,8 @@ export default withMermaid({ text: 'Getting Started', link: `${PATH_TECHNIK}get_started/` }, {text: 'Entwicklungsumgebung', link: `${PATH_TECHNIK}development/`}, - {text: 'Coding Conventions', link: `${PATH_TECHNIK}coding_conventions/`, collapsed: true, items: [ - {text: 'Naming Convention - Testing', link: `${PATH_TECHNIK}coding_conventions/tests_naming`} + {text: 'Coding Conventions', link: `${PATH_CODING_CONVENTIONS}`, collapsed: true, items: [ + {text: 'Naming Convention - Testing', link: `${PATH_CODING_CONVENTIONS}tests_naming`} ]}, { text: 'Adr', link: `${PATH_TECHNIK}adr/`, collapsed: true, items: [ diff --git a/docs/src/technik/coding_conventions/tests_naming.md b/docs/src/technik/coding_conventions/tests_naming.md index eb5690071..f6f78159b 100644 --- a/docs/src/technik/coding_conventions/tests_naming.md +++ b/docs/src/technik/coding_conventions/tests_naming.md @@ -31,19 +31,19 @@ public interface EreignisModelMapper { } ``` -```java +```java{2-3,5-6,11-12} class EreignisModelMapperTest { @Nested - class ToEntity { // Name der zu testenden Methode + class ToEntity { // Name der zu testenden Methode @Nested - class ToEreignisEntity { // nested overload 1 + class ToEreignisEntity { // nested overload 1 @Test void should_returnEreignis_when_givenEreignisModel() {} } @Nested - class ToListOfEreignisEntity { // nested overload 2 + class ToListOfEreignisEntity { // nested overload 2 @Test void should_returnListOfEreignis_when_givenEreignisseWriteModel() {} } From 21efdb9423424e60fcc724bd306302ed84c77b77 Mon Sep 17 00:00:00 2001 From: Viviane Johns <145964798+vjohnslhm@users.noreply.github.com> Date: Wed, 25 Sep 2024 08:46:18 +0200 Subject: [PATCH 3/4] Update docs/src/technik/coding_conventions/index.md Co-authored-by: MrSebastian <13592751+MrSebastian@users.noreply.github.com> --- docs/src/technik/coding_conventions/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/technik/coding_conventions/index.md b/docs/src/technik/coding_conventions/index.md index 03b433d2d..5ee872a9a 100644 --- a/docs/src/technik/coding_conventions/index.md +++ b/docs/src/technik/coding_conventions/index.md @@ -2,4 +2,4 @@ Der Einsatz von Coding Conventions erhöht die Lesbarkeit und Struktur unseres Codes. -Entscheidungen bezüglich der eingesetzten Conventions und wie diese konkret im Projekt umgesetzt werden, sollen hier dokumentiert werden. \ No newline at end of file +Entscheidungen bezüglich der eingesetzten Conventions und wie diese konkret im Projekt umgesetzt werden, sind hier dokumentiert. \ No newline at end of file From b965b0a465a5c8c24d1a611666ee96bc340a6167 Mon Sep 17 00:00:00 2001 From: vjohnslhm <145964798+vjohnslhm@users.noreply.github.com> Date: Wed, 25 Sep 2024 09:51:42 +0200 Subject: [PATCH 4/4] =?UTF-8?q?#414=20update=20kontext=20+=20add=20code=20?= =?UTF-8?q?group=20f=C3=BCr=20codebeispiele?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../coding_conventions/tests_naming.md | 34 +++++++++++-------- 1 file changed, 20 insertions(+), 14 deletions(-) diff --git a/docs/src/technik/coding_conventions/tests_naming.md b/docs/src/technik/coding_conventions/tests_naming.md index f6f78159b..5b4536407 100644 --- a/docs/src/technik/coding_conventions/tests_naming.md +++ b/docs/src/technik/coding_conventions/tests_naming.md @@ -2,8 +2,13 @@ ## Kontext -Damit der Code übersichtlicher und einheitlicher ist, sollen Naming Conventions eingesetzt werden. Damit wird für Tests gewährleistet, dass deren Inhalt klar ist, ohne den Code lesen zu müssen. - +Aktuell gibt es keine Struktur oder Vorgaben bei der Benennung von Tests. Die meisten Namen sind sehr kurz gehalten und wenig aussagekräftig, wie zum Beispiel: +````java +void dataFound() {} +void noDataFound() {} +void serviceCalled() {} +```` +Damit der Gesamtcode im Projekt übersichtlicher und einheitlicher ist, sollen Naming Conventions eingesetzt werden. Grundlage für die Einführung sind unter anderem auch sich wiederholende Tests mit gleichem Inhalt in den verschiedenen Services. So wird gewährleistet, dass deren Kontext schneller klar ist, ohne den Code lesen zu müssen und die Wartung und Erweiterung des Codes wird erleichtert. ## Entscheidung Die Bezeichnungen sollen dem Schema `should__when_` folgen, wobei Result (= ExpectedBehavior, bzw. erwartetes Ergebnis) und Input (= StateUnderTest, bzw. zu testender Zustand) in CamelCase gehalten werden. Dem Schema entsprechend sind die Testnamen auch auf englisch zu formulieren. @@ -20,18 +25,9 @@ void should_throwAccessDeniedException_whenAuthoritiesMissing() {} ``` ##### Gruppierung überladener Methoden: -Vereinfachter Pseudocode! Beispiel aus Vorfälle und Vorkommnisse Service -```java -@Mapper -public interface EreignisModelMapper { - - Ereignis toEntity(EreignisModel model); - - List toEntity(EreignisseWriteModel model); -} -``` - -```java{2-3,5-6,11-12} +Vereinfachter Pseudocode! Beispiel aus dem Vorfälle und Vorkommnisse Service. +::: code-group +```java{2-3,5-6,11-12} [MapperTest.java] class EreignisModelMapperTest { @Nested class ToEntity { // Name der zu testenden Methode @@ -51,6 +47,16 @@ class EreignisModelMapperTest { } ``` +```java [Mapper.java] +@Mapper +public interface EreignisModelMapper { + + Ereignis toEntity(EreignisModel model); + + List toEntity(EreignisseWriteModel model); +} +``` +::: ## Konsequenzen ### positiv