cxf-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Christian Schneider <ch...@die-schneider.net>
Subject [Discuss] CXF Architecture and Architecture Documentation
Date Sat, 19 Feb 2011 12:31:21 GMT
Hi All,

I know that the theme is a big one and likely will spawn some larger 
discussion still I think it is important to talk about it and to have a 
common understanding.
When digging into some not so obvious issues I repeatedly stumble about 
the fact that there are important things about CXF that I donĀ“t know or 
only have a vague clue of.
Another problem I often had is where to put new stuff or decide if a 
classs is placed at a location where it should not be.

These examples show in my opinion that we do not have a good 
architecture documentation and no clean process to decide about 
architecture and to document decisions. So I propose some things
and we see if we reach a consensus.

The first thing is a question that always pops up and that is not so 
easy. What is architecture?
I once read a nice definition that is quite open but still catches what 
is important:
"Architecture is the sum of the decisions about a project that are the 
most expensive to change later. "
Sorry that I am not able to point to a concret source of this. I think 
this definition catches the important thing about architecture. It 
should cover only those things that may later bite you.
So for example the decision it can be argued if the decision for a 
logging framework is an architectural decision as we saw in Apache Camel 
how fast they were able to switch to slf4j. So this was nothing
that was expensive to change. In any case I am curious what you guys 
consider as a good definition for an architecture.

I would like to come to a consensus about what we define as architecture 
as a first starting point.

The next thing is how to document our architecture. We have a good 
starting point at 
https://cwiki.apache.org/confluence/display/CXF20DOC/CXF+Architecture 
but I think some important things are lacking. This page
describes the key structural elements and how some key elements work 
together in CXF. That is very important and we should simply try to 
improve it. I would also like to add our common definition of what 
architecture is to that document.

The first thing I would like to add are architectural goals. An 
architecture can never be good in itself. It can only be judged against 
the goals it tries to achieve. Here again we should only track the most 
important goals.

The second thing I would like to add is a page about architectural 
decisions. It should contain a short description of the process how we 
do these decisions and a list of decisions in a well defined format. I 
would also like
to limit the decisions to a certain number so we are sure that only the 
most important decisions are tracked. I added such a page as my proposal 
and we should discuss if this is ok for all. As I have no idea how many 
decisions we should track I think we could simply start and keep in mind 
that it should not grow too large. See 
https://cwiki.apache.org/confluence/display/CXF20DOC/Architectural+Decisions

I hope we reach a consensus about these things as I think they are very 
important.

Christian




-- 
----
http://www.liquid-reality.de


Mime
View raw message