From 32c9ba7dd13780756e3e33f7bd5218fbd7de2d5b Mon Sep 17 00:00:00 2001 From: Yann Dirson Date: Sun, 8 May 2005 14:25:33 +0000 Subject: [PATCH] more doc --- NEWS | 8 ++++++++ README | 29 ++++++++++++++++++++++++++--- 2 files changed, 34 insertions(+), 3 deletions(-) diff --git a/NEWS b/NEWS index 417d317..a608a36 100644 --- a/NEWS +++ b/NEWS @@ -1,3 +1,11 @@ +Version 0.7 + + Other end-user-visible changes + + * More documentation has been written. + +================================================== + Version 0.6.1 Bugs fixed: diff --git a/README b/README index e504b4b..0d25954 100644 --- a/README +++ b/README @@ -47,8 +47,20 @@ New versions can be found at http://ydirson.free.fr/soft/graph-includes/. HOW TO TAKE ADVANTAGE OF THIS TOOL TO IMPROVE YOUR CODE ------------------------------------------------------- +Graph-includes is only a supporting tool for a refactoring effort. It +can be useful in helping a developper to see where he should put its +efforts in order to get cleaner and saner dependencies in a project. + +In this respect, it is quite similar to a microscope: if you don't +look at the right place, you won't see anything interesting. But if +you start with a small magnifying factor, you can locate regions of +interest, and then zoom on those to get to the interesting stuff. + + 1. on the spirit of dependency cleanup +1.1. first look at a dependency graph + When developping a project of medium size (we'll talk mostly C/C++ here, but that will apply to most languages), expecially with many people writing code, it is quite easy to get to a point where each @@ -61,7 +73,12 @@ included files #include themselves a bunch of other files. For a project of about 100 files, just producing a graph of all those files, with arrows representing the #include dependencies, will usually give an unreadable graph, and will show very little about possible -improvements. +improvements. This is why this tool has been written: to make it +possible to get to the useful information hidden in this unusable +dependency graph. + + +1.2. looking further A less obvious relation appears more clearly when you consider not files by themselves, but the set of files made of an interface and the @@ -92,6 +109,12 @@ dependencies will allow, for example, to select with finer grain which of those modules of code will need to go into which executable, thus producing lighter executables. +Note that such a reciprocal dependency may not be pathological. Many +projects tend to split a large module into several files for clarity, +even when those files are inter-dependant. It is much often in cycles +of unidirectional dependencies that we find dependencies that should +not be there. + In other cases, headers would just have been used to access a type definition from b.h, and the associated b.o would not be needed. In such cases, you may want to consider splitting such "low-level" @@ -351,8 +374,8 @@ TODO - ensure that all provided non-abstract classes are self-contained -BUGS ----- +KNOWN BUGS +---------- - --showdropped mode draws too many edges as dropped (ie. does not consider marked edges as dropped when deciding whether to consider -- 2.11.4.GIT