Revisiting the directionality of edges (Nov 2018)

[jayqi]

Right now we have a convention:

    # Convention: If B depends on A, then B is the TARGET 
    # and A is the SOURCE so that it looks like A -> B

This was chosen as the convention by democratic polling among pkgnet authors back about a year ago or so.

I would like to reopen the discussion for the reason that our current convention disagrees with UML which a lot of other applications out there follow.

Unified Modeling Language (UML)

UML is a widely used modeling framework for software engineering that is also an ISO standard.

For diagramming dependencies:

In the UML, this is indicated by a dashed line pointing from the dependent (or client) to the independent (or supplier) element. The arrow representing a Dependency specifies the direction of a relationship, not the direction of a process.

For class diagrams showing inheritance

To model inheritance on a class diagram, a solid line is drawn from the child class (the class inheriting the behavior) with a closed, unfilled arrowhead (or triangle) pointing to the super class.

[jayqi]

Examples of other people:

Dependency graph

I googled "dependency graph visualization" and clicked on a bunch of stuff on the first page. Everything I looked at either had no directionality or had directionality consistent with UML: dependent -> independent.

Dependent -> Independent

Examples using this convention:

• Doxygen (2,195 stars), the C++ docs generator, makes call graphs this way (example)
• Haskell Tool Stack (2,911 stars)
• objc-dependency-visualizer (1,265 stars)
• goviz (620 stars)
• gpdepgraph (351 stars)
• dependency-cruiser (217 stars)

Independent -> Dependent

Didn't find any.

Inheritance graph

Child -> Parent

Examples using this convention:

• Doxygen (2,195 stars), the C++ docs generator, also makes class diagrams this way ([example])(https://sunglint.wordpress.com/2013/03/04/doxygen-vs-graphviz/)
• PyCharm and IntelliJ specifically use UML
• Pylint has a UML class diagram generator

Parent -> Child

Examples using this convention:

• Sphinx, the Python docs generator

[jameslamb]

I think @jayqi makes a pretty convincing point that we should switch the order of inheritance.

If we decide to, I think we need to pull this into v0.3.0 milestone since I want to do some publicity around that release and it would suck to get people into using pkgnet and then release a big breaking change in a followup release.

[jayqi]

I think this also makes more sense if we consider the network measures we calculate.

For example, PageRank:

PageRank works by counting the number and quality of links to a page to determine a rough estimate of how important the website is. The underlying assumption is that more important websites are likely to receive more links from other websites.

In the Independent -> Dependent convention, a function is considered high-score if it has a dependency on functions that depends on a lot of other functions? This measures some sort of complexity of a function and not its importance in graph. People usually don't use PageRank in this way.

Whereas in the Dependent -> Independent convention, a function is considered high-score if it is depended on by functions that are depended on by a lot of other functions. This is more in-line with the normal interpretation of PageRank, which measures importance of a node.

[bburns632]

Ok @jayqi & @jameslamb. You make a convincing argument. What I am hearing is that there is a UML convention and adhering to that convention will make it easier to integrate with other packages and for them to integrate with us. The only potential counterpoint I can think of is edge aesthetics which is subjective and a minor point comparatively.

Let's fit this in the next release, v0.3.0.

[jayqi]

It's funny Sphinx is the only one that does it the other way. There's a two-year-old open issue about it where people say it's more common to see the UML convention.