Skip to content

Commit

Permalink
Merge pull request #7886 from vinay-s36/patch-1
Browse files Browse the repository at this point in the history
documentation: fixed grammatical errors and typos
  • Loading branch information
pascalgrimaud authored Oct 30, 2023
2 parents 2cb2fb8 + 146f5d8 commit 2f690cb
Show file tree
Hide file tree
Showing 2 changed files with 10 additions and 10 deletions.
16 changes: 8 additions & 8 deletions documentation/hexagonal-architecture.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Hexagonal architecture (application service flavor)

Good evening and welcome to this architecture documentation. Glad you made your way there! By the time of your reading this documentation may be outdated, feel free to update it!
Good evening, and welcome to this architecture documentation. We're pleased that you've found your way here! Please note that this documentation may become outdated over time, so feel free to update it as needed.

So, this is basically about why and how to use a peculiar flavor of [hexagonal architecture](https://alistair.cockburn.us/hexagonal-architecture/).

Expand All @@ -21,27 +21,27 @@ Here are some of the properties we are looking for when using this kind of archi

### Built for changes

"The Only Constant in Life Is Change."- Heraclitus. This can't be more true in Software (hence [the name](https://en.wikipedia.org/wiki/Software)) and, if you have just a few weeks of experience, you know that "the users don't know what they want!!!". If the first quote is true the second one is fallacious!
"The Only Constant in Life Is Change."- Heraclitus. This can't be more true in software (hence [the name](https://en.wikipedia.org/wiki/Software)) and, if you have just a few weeks of experience, you know that "the users don't know what they want!!!". If the first quote is true the second one is fallacious!

It's not that the users don't know what they want, in fact, nobody knows. Building a Software is not done with somebody telling the others what to do, it's done with [productive partnerships](https://manifesto.softwarecraftsmanship.org/). Yes, that means people will change their mind times and times again (and this is totally fine!).
It's not that the users don't know what they want, in fact, nobody knows. Building a software is not done with somebody telling the others what to do, it's done with [productive partnerships](https://manifesto.softwarecraftsmanship.org/). Yes, that means people will change their mind times and times again (and this is totally fine!).

So, as professional software developers we have to ensure that the code we are writing can welcome those changes. This often starts by lowering the solution complexity!

We often talk about 3 types of complexity:

- **Essential**: When building Software we have to solve a problem of complexity X: this is the essential complexity. This complexity directly relates to the problem we are trying to solve and we can't really make that lower.
- **Essential**: When building software we have to solve a problem of complexity X. This is the essential complexity. This complexity directly relates to the problem we are trying to solve and we can't really make that lower.
- **Mandatory**: No matter the efforts, we are gonna have to add some complexity to the system since we have technical stuff to do (persist data, send messages, ...). This complexity is called mandatory complexity.
- **Accidental**: On top of the two previous complexities comes the accidental complexity, the one we don't want because it's not needed. Example: if you have a configuration that is standing still for the past 10 years you probably don't need to put that in a database, handling that in code will be easier and more efficient (and no, you probably don't need microservices with one team of 3).
- **Accidental**: On top of the two previous complexities comes the accidental complexity, the one we don't want because it's not needed. For example, if you have a configuration that has been standing still for the past 10 years, you probably don't need to put that in a database, handling that in code will be easier and more efficient (and no, you probably don't need microservices with one team of 3).

The hexagonal architecture allows us to reduce all those complexities to their bare minimum by giving clear responsibilities to each part of our Software.
The hexagonal architecture allows us to reduce all those complexities to their bare minimum by giving clear responsibilities to each part of our software.

The very clear Separation Of Concern enforced by the architecture eases automatic testing of each parts since it's only doing one thing. Being able to build solid tests is also a great way to build a changes welcoming Software!
The very clear separation of concern enforced by the architecture eases automatic testing of each parts since each part is only doing one thing. Being able to build solid tests is also a great way to build a change welcoming software!

> Even if the architecture eases tests writing, being able to write good tests takes times and practice!
### Shorten feedback loops

In Software development if you want to go faster (like really faster) you'll have to go for short feedbacks loops. If you have a button that can tell you in a few seconds that your solution is still behaving as intended you'll be way faster than checking that by hand after any update (in fact, you won't check by hand that after any update...).
In software development if you want to go faster (like really faster) you'll have to go for short feedbacks loops. If you have a button that can tell you in a few seconds that your solution is still behaving as intended you'll be way faster than checking that by hand after any update (in fact, you won't check by hand that after any update...).

Let's be honest here: hexagonal architecture won't help for the fastest feedback loops which are pair feedback in [pair](https://en.wikipedia.org/wiki/Pair_programming) or [mob programming](https://en.wikipedia.org/wiki/Mob_programming).

Expand Down
4 changes: 2 additions & 2 deletions documentation/module-creation.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Creating a JHLite module

So you want to create a JHLite module? Great!
So, you want to create a JHLite module? Great!

For that you'll need to provide 2 main parts:

Expand Down Expand Up @@ -182,7 +182,7 @@ In your `JHipsterModuleResource` you can define additional properties and an org

## Applying module in CI

Now that you are confident about your module action you can add it to the JHLite ci by adding it in the `fullapp` application in [generate.sh](../tests-ci/generate.sh) so it will be compiled and analyzed by SonarQube. You can also create a brand new app if needed.
Now that you are confident about your module's action you can add it to the JHLite ci by adding it in the `fullapp` application in [generate.sh](../tests-ci/generate.sh) so it will be compiled and analyzed by SonarQube. You can also create a brand new app if needed.

If your app launches a docker container, you must edit [start_docker_compose.sh](../tests-ci/start_docker_compose.sh).

Expand Down

0 comments on commit 2f690cb

Please sign in to comment.