LG-03-04-design-principles-need-better-references

[gernotstarke]

For this important LG we don't provide adequate references.

• abstraction:
• modularization: Parnas?
• encapsulation
• separation of concerns
• open closed
• dependency inversion
• high cohesion
• low coupling
• conceptual integrity: Brooks?
• complexity reduction, simplicity:
• expect errors
• yagni
• dry

These principles are a MAJOR SOURCE for future exam questions, therefore we should invest in collecting reliable, well-known sources.

[skogsbaer]

I started working on this issue by looking what terms are already part of the glosssary:

Already linked to glossary

• encapsulation (without citation in glossary)
• separation of concerns (without citation in glossary)
• open closed principle (needs proper citation in glossary)
• dependency inversion (has citation in glossary)
• high cohesion (without citation in glossary)

Action needed: improve glossary with proper citation

Already with references:

• low coupling [Ford+2021], but in LG-03-06

Action needed: none

With a glossary entry

• abstraction
• conceptual integrity: Brooks?
• LSP

Action needed: link to glossary, add reference to glossary

Without glossary entry (but we should have one)

• yagni
• dry

Action needed: write glossary entry with reference, add link to glossary

Other

• expect errors
• complexity reduction, simplicity

Action needed: add reference

[skogsbaer]

One principled question for @gernotstarke and every else: what kind of references are most useful?

For example, for the term "modularity" David Parnas' article "On the Criteria To Be Used in Decomposing Systems into Modules" is probably the correct historical reference. But its from 1972. There are modern books, which could also serve as a good reference, e.g. Ford+2021 has at least two chapters about modularity and decomposition. There are many other books that could also serve as a reference, the difficulty is now to decide "which is the best reference".

Another example: for the term "separation of concerns", a historical reference would be Dijkstra's essay "On the Role of Scientific Thought" (or again Parnas). But this essay is from 1982 and difficult access.

My suggestion is: have a good explanation in the glossary and give the correct historical reference (if possible).

What do you think?

[ulibecker]

I like the approach suggested by @skogsbaer to "have a good explanation in the glossary and give the correct historical reference (if possible)"

[gernotstarke]

I understand your suggestion as follows:

1. give a understandable ("good") explanation in the glossary
2. add (maybe historical) references also in the glossary

[gernotstarke]

see PR #669

[gernotstarke]

we tranform this suggestion into ADR-012