Define thoroughly the iai design principles

[lorenzogrv]

This issue belongs to project's Life Cycle Planning Phase. outdated assumption

This definition is being written on the Design Principles document at the wiki.

TODO

• [ ] READ section should be improved as it's guru text now
• [ ] Avoid known blunders:
  • Note this section is heavily based on resources from the c2 wiki
  • [ ] Refactor avoid prematurity (cause=generalization) (premature generalization=rule of thumb)
• [ ] OOD principles
  • [ ] Introduction should note this is mostly based on "uncle Bob"'s work
  • [ ] Forget that class -> builder thing, and just apply principles to every software entity
  • [ ] Most principles that note an "unexistant" rule of thumb, already have one. Refactor to provide them.
• [ ] Review the full document and note every author on the contrib page (unaware contributors)
• [ ] Triage this issue comments and migrate them to an "Architecture" issue when it proceeds.
• [ ] The document does not render as expected with the firefox extension I'm currently ussing to render local .md files. Related to embeded html tags for navigation. This concerts the HTML5MD convention.

It seems that the "design principles" document is going too wide. architecture design principles should fit on the same place than object oriented design principles? principles to avoid known blunders should fit on the same place than other design principles?

(laconbass @ January 2015)

---

OOD principles seem to be an architecture thing. READ seems better titled as Principles for research. The READ introduction seems the manifesto, the origins of principles. Are principles a tool? Sure

@laconbass, February 2016

[lorenzogrv]

(...)

The previous paragraph leads me to think on the very first principle being about writing the principles themselve.

A bit of mental verbiage,

Modular and layered system

There must be modules differentiated by its responsability, that's the feature they add to the application.

There must be layers differentiated by its responsability, that's the role they play on the design.

Is this an architecture-related thing? not sure

[lorenzogrv]

Today I discovered loopback, that guys at strongloop got on the path really well. Leading from there, I readed some "philosophically" interesting · things that leaded me to meet no backend.

noBackend is an approach to decouple apps from backends, by abstracting backend tasks with frontend code. This allows frontend developers to focus on user experience and gives backend developers more flexibility on the implementation side.

I like the idea of completely abstracting the frontend from the backend, as the usual schema that pisses off mine head daily is Content <- -> Backend <- -> Frontend. Maybe that no-backend philosophy can help defining that level of abstraction.

Anyway, this seems more a architecture-related thing.

[lorenzogrv]

Researching on loopback I met the swagger project and shred.

The former seems exciting in relation to quickly create applications by generating them automatically by "parsing" its specification. That seems enought to create an app as fast as say iai :smile:.

The latter, well its cofeescript and I hate it, but has a really interesting aproach about constructing resources to define apis, and stacking them in a composite-like hierarchy by returning a function on the builder that is a binding to add another resource as a child of the new instance. Crazy, funny, and interesting.

Things went crazy when I discovered the RFC6570 for URI Templates, that must be adopted for sure. There are some implementations, also written in javascript, and in the worse scenario there is a github repo with the test cases, I hope there is no need on writting a module for that.

[lorenzogrv]

After reading this excelent article by Joe Gregorio, one of the authors of the RFC6570, the words I used to have written on a paper at the wall of my room came to my mind...

Don't be a framework

[lorenzogrv]

After researching on the work of the "Uncle Bob", and prior to integrating the object oriented design principles into the iai design principles, makes sense a very first principle to keep on stage the foundations of defining the iai design principles.

[lorenzogrv]

I started the wiki to keep there the work done and in progress, and here the discussion with myself for reference.

[lorenzogrv]

Wiki page for contrib contents

While researching practical aproaches to apply the Single Responsibility Principle on the c2 wiki (they call it One Responsibility Rule

In OO, a class's statement of responsibility (a 25-word or less statement) is the key to the class. It shouldn't have many 'and's and almost no 'or's.

This seems a good rule of thumb :+1:

Even the experts appear to question the SRP, but it seems the conclusion is this principle is key and useful when applied correctly.

I also met the work of Rebecca Wirfs-Brock (lots of resources here)

[lorenzogrv]

I must put the red line about Don't Reinventing The Wheel somewhere.

• http://c2.com/cgi/wiki?ReinventTheWheel
• http://c2.com/cgi/wiki?ReinventingTheWheel
• http://en.wikipedia.org/wiki/Reinventing_the_wheel

NIH Syndrome

• http://c2.com/cgi/wiki?NotInventedHere
• http://en.wikipedia.org/wiki/Not_Invented_Here

[lorenzogrv]

While cleaning the repo readme, this seems to be likely a desing principle thing rather than a goal thing:

Could this be more an "avoid known blunders principle"??

Content Management System Strategy

The CMS should be the application, not the framework.

[lorenzogrv]

Ending here after thoughts about something, maybe the iai-dean, doing code analysis to ensure desing principles are fullfiled. Deeping in the roots of plato, a tool i've already used, I've found escomplex, that seems a nice point to start.

Anyway this is really a topic about the architecture of the system, not about its design principles.

[lorenzogrv]

Comming from a brief look at the website of Martin Fowler. It seems there are lots of stuff in his articles that can be a valuable knowledge.

Maybe you will never read this, but thanks for sharing your knowledge, Martin.

[lorenzogrv]

Wow, I were starting my thoughts about the 3rd principle, reading on the c2 wiki about the NIH syndrome and I read interesting things and also funny things by some guru, posting here for reference.

The conclusion I extract from the latter is:

No one has the absolute knowledge about something, is the whole community that has the absolute knowledge about anything

That's, there are 2 kinds of gurus: the ones that think they are, and the ones that don't know they are. I hope to meet more of the latters than the firsts :smile:

[lorenzogrv]

Ok, that was the last adition for a while. That's the moment to work harder on #2 and see what can be done with #4.

[lorenzogrv]

While starting to work on #4 I felt like I was missing Convention over Configuration on the design principles. I should check it

[lorenzogrv]

Added convention over configuration to the design principles.

I also recently met the work of Charles Antony Richard Hoare through a cite on wikipedia:

“there are two ways of constructing a software design: one way is to make it so simple that there are obviously no deficiencies; the other way is to make it so complicated that there are no obvious deficiencies. The first method is far more difficult."

How about changing the "A" on "reAd" to *Avoid the guruism"? :laughing:

[lorenzogrv]

An interesting article about the principles of Service Oriented Architecture http://www.infoq.com/articles/updated-soa-principles

Is this a principle thing or an architecture thing?

[lorenzogrv]

After researching the twelve-factor app "manifesto", the titles of two books written by Martin Fowler shine:

• Patterns of Enterprise Application Architecture
• Refactoring

[lorenzogrv]

Nice paper about the principles of design that summarizes well the use the elements of art in a work of art (J. Paul Getty Trust 2011).

[lorenzogrv]

Working hard on avoid known blunders. I'm basing the research heavily on the c2 wiki, but I should grab information also on other places.

[lorenzogrv]

Commited changes just now, added some TODOs. I should move forward and see how changes affect the planning, and come back later.

It must be determined if the twelve-factor app thing fits here or not.

[lorenzogrv]

While drafting the data validation layer, I met the concept of Inversion of control. It is related to the dependency inversion principle, but not the same. While researching the concept I found an awesome paper called Designing Reusable Classes that offers some clues (rules).

Jumping here and there, I've met the Law of Demeter. The original paper is available, for my pleassure.

More architecture related, and data-validation too, Strategy seems a nice pattern to suffice my thoughs about the complexity of validating complex structures but it's time to make an effort on providing just the features needed at this moment (simplifying), and refactor later if need, applying YAGNI.