Hexagonal blog

[iluwatar]

This is a pull request for a blog post about Hexagonal Architecture. The code samples have been embedded using gist-it. Looking forward to your comments.

[markusmo3]

So i havent read your blogpost from start to finish 100%, as this isnt my style in general, i always scroll back and forth to scan for relevant information in posts and only want to read the good information.

At the very beginning the explanation is good, once read through, without much skipping i got the general idea of the pattern. 👍
But when the code explanation starts it gets quite hard with my style of reading, as important parts arent highlighted, or in another way specially presented. The code is just shown in a wall of text code. But if i skip the whole file i miss important information and selectively picking out important parts is hard as mentioned above.

Some code parts are also included that i think of unnecessary, like the LotteryTicket#hashCode #equals, getter methods and imports. I dont think the reader needs those informations right at the moment he/she comes in first contact with the new pattern (well, i didnt at least).

The page-filling amount of code breaks the "flow" for me, its like that for me:
I see a complete source file, think okay, well lets look at it. I understand it, scroll down a bit, see more source files, read them a bit, but also get more and more impatient reading through and sifting out important information that i just skipped the last source files and looked up different blog posts about this pattern. Maybe im just too impatient, but that is my way of reading blogposts.

For me the blogpost is still valueable, as the code often does contain good commenting and explanation. I just think there has to be a better way of representing the informations and comments in different way than just cating the files.

Dont get discouraged by me! I really ❤️ the idea of a blogpost explaining the pattern in detail and i think this is what jdp really needs at this point.

[iluwatar]

@markusmo3 thanks for the review and valuable comments. I'll try to cut down the amount of code, especially the irrelevant parts. I understand it can be disheartening for the reader to have to read hundreds of lines of code at once.

[npathai]

My doubt regarding lottery system was not regarding the name. Should lottery system be cled a port? And if yes then what will be different adapters of this port?

[iluwatar]

@npathai I won't publish this weekend so you have time to suggest the new image. Can you elaborate a bit more the idea of lottery system port? How would you change the system?

[npathai]

@iluwatar There you go. Not exactly my idea, saw it being used somewhere, found a creative commons image and edited it to add blogpost title. Hope you like it.

[npathai]

@iluwatar My concern in the present explanation is that the core of the system does not contain any business logic, there are only data structures like LotteryTicket, LotteryNumbers and PlayerDetails. The domain of the system must contain logic that remains the same and through ports and adapters we are able to test the domain and run it in multiple environments without the change leaking into the core.

One of the reason hexagonal architecture is utilized is ease of testing the system without dependency on database or such, but in our system there will be nothing to test but the datastructures. This feels a little weird to me. Shouldn't business logic of how ticket numbers are selected be part of the core domain and not a port? Any insights would be great. Thanks 👍

[iluwatar]

@npathai Yes, I tend to agree with you comment that the core should include domain logic. I think I will try to add another class LotterySystem that provides interfaces for LotteryService and LotteryAdministration. Basically the system will work the same but the domain logic will move to the core. Does that sound about right?

I like the new image and will try to use that instead of the controversial nut 😁

[iluwatar]

@npathai The work is ready for another review. I've made the changes as described in the previous comment.

@markusmo3 I understood the feature concerning gist-it and commit hashes is ready? Could you instruct me how to add those commit hashes?

[npathai]

A better name for LotteryNotificationsImpl would be ConsoleNotifications. Also if the interface represents an entity that will send out notifications then the name can be something like LotteryEventNotifier, and the console implementation can have name ConsoleNotifier and maybe a SMSNotifier.
Also in the code there are *Impl classes, I am not fond of names like *Impl, rather the implementation should describe how it does, what it does. Plus why do classes like LotterySystemImpl hardcode their dependency on LotteryNotificationsImpl, LotteryTicketInMemoryRepository, WireTransfersImpl. Out of these lottery ticket repository and Wire Transfers are dependencies of the system and should be injected using constructor. What if we wanted to test the system using MongoTicketRepository?

[markusmo3]

@iluwatar Sure.

Have a look at the last comment here: #486
Its standard jekyll/liquid usage:

{% include gistit.html file="visitor/pom.xml" slice="2:4" %}

{% %}: means its a jekyll command
include gistit.html: is the jekyll command to be executed, in our case an include (could also call that an import)
file="visitor/pom.xml" slice="2:4": are include parameters that are given to the gistit.html file

Such include parameters for external use are always documented in the include file itself

Due to jekyll not "really" being a programming language some stuff might sound a bit wierd, but those includes/imports could also be imagined as a method/function, taking parameter and returning html code.

Hope this clears it up a bit.

EDIT: The hash thing might be something to easily miss. Pseudo Code:

IF parameter "tag" is set THEN display the code from the tag only (e.g. branch "hexagonal")
ELSE IF page variable "hash" is set THEN display the code from that commit hash only (e.g. "hash: 732774f" for your commit "Remove unused image" (*1) )
ELSE just use the tag "master" (HEAD)

Reminder: a page variable is the things in the front matter

(*1): 732774f

Further reading: https://jekyllrb.com/docs/templates/#includes

[iluwatar]

@npathai can you take another look now? I've moved the logic to the core, introduced Mongo based adapters and console user interfaces for players and administrators.

Additionally @npathai , could you update the lottery system picture so that Notifications port becomes Event log?

[npathai]

@iluwatar Sure I will review and update the diagram on this weekend.

[npathai]

@iluwatar Here is the updated diagram

[npathai]

@iluwatar I am done with review. It seems good to go. Great job done on this blog. 👍

[iluwatar]

@npathai @markusmo3 thank you very much for the help! The blog post just went live.

[iluwatar]

@all-contributors please add @markusmo3 for design code ideas

[allcontributors]

@iluwatar

I've put up a pull request to add @markusmo3! 🎉