RFC: More Emphasis on Core Principles of Helix

[nickwesselman]

Feedback on Helix and its use indicates that at times, developers get caught up in the specific practices and conventions, and get stuck when it's not clear how to follow them. There are also cases where Helix is seen merely as an organizational structure for projects. Understanding the core principles -- the "why" -- is actually more important than the conventions themselves to help overcome these issues.

The Helix Workshop gets rather deep on the Robert Martin principles which provided much of the foundation for Helix:

• Reuse-Release Equivalence Principle (REP)
• Common-Reuse Principle (CRP)
• Common-Closure Principle (CCP)
• Acyclic-Dependencies Principle (ADP)
• Stable-Dependencies Principle (SDP)
• Stable-Abstractions Principle (SAP)

These principles are also outlined in Chapter 28 of Agile Principles, Patterns, and Practices in C#.

Of only slightly lesser importance is the intention of Helix to provide a shared language across the community that can be used to "standardize" implementations. This includes layer naming, "interface" templates, etc.

There is some documentation on Architectural Principles in Helix already, but how do we better communicate the "why" of Helix? Is it a matter of moving this section to a more prime position? New content needed? Better/simpler explanations of the core principles?

[TwentyGotoTen]

Yes! I actually attended that workshop a year ago and for me it was a real eye-opener. The emphasis on the packaging principles really boils Helix down to its essence.
That said, it can be pretty dense stuff. So rather than rewriting chapter 28 of the Uncle Bob book, be sure to talk Sitecore language as much as possible. A while back I wrote a blog post in which I tried summarize the Helix principles without getting too heavy on the theory. It's received by far the most positive feedback I've had for any post, so I think there's definitely an appetite in the communiy for this kind of documentation.

[derekcorreia]

Agree with this proposal. One of the goals we had in having the workshops was to be able to connect with Architect-level folks at customers and partners and try to make sure we driving home the base principles of Helix. The conventions are a great way of following the principles, but our base documentation could go deeper here without just handing off. If there's any place where depth is appreciated, it's in the documentation.

I'd suggest that we expose the principles at high level throughout and hyperlink them to a deeper dive section when referenced. That way, we can continue to drive any ambiguity back to documentation on the core principles, but leave the documentation flowing so as not to duplicate content.

[muso31]

I think there's an aspect of 'why' that isn't promoted enough... in that by adhering to a convention (or 'shared language' as you mention) we're removing the dependencies on specific people/architects. If someone takes over your project they instantly have knowledge in how it's built, or if not they can visit https://helix.sitecore.net/

A lot of architects don't like that, but 'thinking about the next dev' is important and a big plus to adhering to a convention. Infact, I'd argue alone it's a reason to use a convention based implementation. Even if you don't feel that the Helix implementations are as good as your own 'shared language', you'll never top the fact that it's easier for the next person to follow, and that the next person has likely heard about the Helix approach. Discussions about Helix seem to get hung up on the finer technicalities and overlook this point

[TwentyGotoTen]

@muso31 As much as I (and countless others) complain about an over-reliance on Habitat, I do follow its conventions. The reasons are exactly as you've outlined. But my concern is that following the conventions alone, without some of the underlying theory can still leave you with a screwed up solution. The challenge as I see it is about making the neccesary skills accessible enough so that the next dev can easily pick up the solution.

[cardinal252]

If you are to get into the core principles of Helix, I feel you need to flip a lot of the reasoning on its head and start working back down from 'how is this stuff going to be deployed'. I feel a lot of developers get hung up on the rules and don't really consider the fundamental goal of delivery. CCP for example only makes proper sense with boundaries of delivery in mind. The majority of Helix solutions I have seen to date are not split around the boundaries of delivery, they are split around logical grouping that an architect feels they need to understand their world. Common reuse is similar.. the majority of the presentation level code in a sitecore solution is really only delivered once, so is unavailable for sensible reuse etc etc

[TwentyGotoTen]

I appreciate that Sitecore sites will rarely, if ever, be deployed in the way that Uncle Bob was thinking when describing the cohesion principles. But I still think there's value in applying them. They help to guide my thinking about how the solution will grow and adapt over months and years.
My team debates these issues everyday during a Sitecore project. Sure, the discussions aren't always fruitful or siginificant, but they do ensure that eveyone is at least thinking about the long term sustainability of the solution.
I suppose you could argue that this is all part of being a good developer/architect and that it shouldn't need to be spelled out. But I think we have to be pragmatic and understand that most people do need some guidance on this stuff. For me, these principles offer a simple (though admittedly not perfect) way to achieve some consistency of approach.

[cardinal252]

Another concern would be that, by design, dependency stability should really mandate that foundation components are changed less than feature and feature less than project. Having all the code in a single solution is bad enough, but with zero seperation between boundaries, you are even more likely to end up with a spaghetti solution. I would potentially argue that at its core, Foundation (at least) should be in a more protected area of the codebase (potentially delivered by nuget packages and the like) to really hammer home this practice. It has been my experience in projects, that developers will change anything they can get their hands on, by having code in the same solution they are more likely to be tempted and the only gate for this is review.

Further to the above, you are FAR less likely to be able to track interdependency between components at the same level - whilst this, I don't think is actually an issue at all - Helix principles dictate it's a no-no, so again.

If you are gonna go with this approach, why not just have everything in a single project, it's about as useful and achieves 95% of the goal you are looking at here.

In addition much of your high level tooling will just show your foundation > feature > project which you already knew. It would be much more difficult to see (as an example) at a modular (think assembly) level that project.newslettersignup > feature.contactlistmanager > foundation.comms.emailbuilder > foundation.comms.net

[nickwesselman]

In addition much of your high level tooling will just show your foundation > feature > project which you already knew.

Soft dependencies (e.g. templates or magic strings) will potentially have this issue no matter what the project structure. Though this is more a commentary on Solution structure, I wouldn't recommend grouping modules in a project without some other tooling to help with the hard dependencies, e.g. FxCop rules (e.g. those already available from Hedgehog). Either way, code review / pull requests would be important, even when enforcing those modules with VS Projects.

The right approach and tooling are ultimately going to depend on the size of the team, the scale and size of the solution, etc. All the more reason IMO to better emphasize the "why," show multiple examples, and emphasize the pros and cons.

[dsolovay]

I think material on these principles, and perhaps the SOLID ones too, would help the docs. I would recommend treating them in two passes. First in the introductory material, discuss them in general terms (why they are beneficial, what each one means, and perhaps some non-Sitecore examples). Then at the end of the document, relate each to specific examples from the Helix document body, to show the connection between the principles and the specific Helix precepts. That will help reinforce the principles, and make the motivation behind the precepts clearer. ("The common closure principle states that ... That is why in Helix ... ")

Notes:

• The SOLID principles seem important for the management of abstractions (e.g DIP), which discuses how layers should communicate through abstractions. The best approach here is not clear to me, as to some extent, the SOLID principles are subsumed in the package principles, and we shold be careful to avoid making the document to theory heavy. Perhaps just mentioned them in passing?
• Robert Martin's treatment of the SOLID and Packaging principles can provide some inspiration to this document, as he postions each in terms of the specific pain points it is meant to address, as well as discussing the pitalls of over zealous application.

[dsolovay]

Some more thoughts here:

1. I think it makes sense to keep the discussion rooted in the Layers section (2.1.2). There is a critical section of the document, and removing the discussions from this section would weaken it.
2. I think a discussion of SOLID would help anchor the presentation of the Package Design principles, and also help readers understand some of the motivation around how elements such as Interface Templates are handled. Since SOLID is tangential (it deals with classes, not packaging), I think a text box towards the head of this section, perhaps entitled "Helix and SOLID", would make sense. This discussion will briefly explain the principles, relate them where appropriate to Helix practices (e.g. Interface Temlates), and use them to anchor an understanding of how introducing abstractions (via interfaces, abstract classes) can hedge against volatility. (Okay to reference Alan Coates article, or would that be an Acycle Dependency?)
3. Expanding the discussion of Stable Abstractions (to reenforce the ideas that the Foundation holds a common language of abstractions that allow loosely coupled feature communication) and Acyclic Dependencies as a way to guard against creeping monolythic architecture (through hidden linkages, omnscient switch/case statements) or rigid inheritence modeling (template inheritence modeled in interfaces).
4. There may be opportunities to sharpen the discussion of the other four principles, but they are reasonably well fleshed out, so should not be a focus.

[dsolovay]

I've written a draft of an appendix that goes over these principles in their original class design context, and seeks to relate them to the specific Helix practices they inspire. Interested in feedback on whether this addresses this RFC and is useful addition to the document, and how it can be improved.

[AmitKumar-AK]

@nickwesselman

• Template Types link in section 4.1.1.2. The Common Reuse Principle (CRP) not working and redirecting to 404 page (https://helix.sitecore.net/appendix/principles/templates/template-types.html).
• References from code link in section 4.1.2.1. The Acyclic Dependencies Principle (ADP) not working and redirecting to 404 page (https://helix.sitecore.net/appendix/principles/templates/references.html).

[nickwesselman]

@AmitKumar-AK thanks! can you log as new issue please?

[AmitKumar-AK]

Sure. BR, Amit Kumar Sent from Mobile. Please ignore typos & brevity.

…

________________________________ From: Nick Wesselman <[email protected]> Sent: Friday, December 13, 2019 9:50:48 PM To: Sitecore/Helix.Docs <[email protected]> Cc: Amit Kumar <[email protected]>; Mention <[email protected]> Subject: Re: [Sitecore/Helix.Docs] RFC: More Emphasis on Core Principles of Helix (#20) @AmitKumar-AK<https://github.com/AmitKumar-AK> thanks! can you log as new issue please? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub<#20?email_source=notifications&email_token=AGYRRK7TYWPBY5GV6FPT2SLQYOY6BA5CNFSM4GCVKQR2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEG2OWVY#issuecomment-565504855>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/AGYRRK4WBROU2ZBXJVSPXDTQYOY6BANCNFSM4GCVKQRQ>.