How to go about describing my software with a component diagram?

[marc nicole]

Hello community,

I have created a Python code where a main algorithm uses three different
modules (.py) after importing them.

To illustrate and describe it I have created the following component
diagram?


[image: checkso.PNG]

Could it be improved for better description and readability?


Thanks!

[marc nicole]

the diagram is also attached here

Post by marc nicole
Hello community,
I have created a Python code where a main algorithm uses three different
modules (.py) after importing them.
To illustrate and describe it I have created the following component
diagram?
[image: checkso.PNG]
Could it be improved for better description and readability?
Thanks!

[Stefan Ram]

Post by marc nicole
Could it be improved for better description and readability?

ASCII art is very readable in Usenet.

With Unicode:


┌─────────────────┐ ┌─────────────────┐
│ Component A │ │ Component B │
│ │ │ │
│ ┌───────────┐ │ │ ┌───────────┐ │
│ │ Interface │<>┼──────┼─>│ Interface │ │
│ └───────────┘ │ │ └───────────┘ │
│ │ │ │
└─────────────────┘ └─────────────────┘
│ │
│ │
│ │
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ Component C │ │ Component D │
│ │ │ │
│ ┌───────────┐ │ │ ┌───────────┐ │
│ │ Interface │<>┼──────┼─>│ Interface │ │
│ └───────────┘ │ │ └───────────┘ │
│ │ │ │
└─────────────────┘ └─────────────────┘

With plain ASCII:

.----------------. .----------------.
| Component A | | Component B |
| | | |
| .-----------. | | .-----------. |
| | Interface |<+------+->| Interface | |
| '-----------' | | '-----------' |
| | | |
'----------------' '----------------'
| |
| |
| |
v v
.----------------. .----------------.
| Component C | | Component D |
| | | |
| .-----------. | | .-----------. |
| | Interface |<+------+->| Interface | |
| '-----------' | | '-----------' |
| | | |
'----------------' '----------------'

With turtles (there are some errors, but one get's the idea!):

import turtle

def draw_box(t, width, height):
for _ in range(2):
t.forward(width)
t.right(90)
t.forward(height)
t.right(90)

def draw_component(t, x, y, label):
t.penup()
t.goto(x, y)
t.pendown()
draw_box(t, 160, 100)

# Draw interface
t.penup()
t.goto(x + 20, y - 40)
t.pendown()
draw_box(t, 120, 30)

# Write component label
t.penup()
t.goto(x + 80, y + 70)
t.write(label, align="center", font=("Arial", 12, "normal"))

def draw_arrow(t, start_x, start_y, end_x, end_y):
t.penup()
t.goto(start_x, start_y)
t.pendown()
t.goto(end_x, end_y)

# Draw arrowhead
t.setheading(t.towards(end_x, end_y))
t.right(150)
t.forward(10)
t.backward(10)
t.left(300)
t.forward(10)

def main():
screen = turtle.Screen()
screen.setup(800, 600)
screen.title("Component Diagram")

t = turtle.Turtle()
t.speed(0) # Fastest drawing speed

# Draw components
draw_component(t, -200, 150, "Component A")
draw_component(t, 100, 150, "Component B")
draw_component(t, -200, -100, "Component C")
draw_component(t, 100, -100, "Component D")

# Draw arrows
draw_arrow(t, -40, 125, 100, 125)
draw_arrow(t, -120, 50, -120, -100)
draw_arrow(t, 180, 50, 180, -100)
draw_arrow(t, -40, -125, 100, -125)

t.hideturtle()
screen.exitonclick()

if __name__ == "__main__":
main()

[Michael Torrie]

Post by marc nicole
the diagram is also attached here

This text-only mailing list does not allow attachments, just FYI.

[marc nicole]

it is here Loading Image...

Le mar. 24 déc. 2024 à 20:03, Michael Torrie via Python-list <

Post by Michael Torrie

Post by marc nicole
the diagram is also attached here

This text-only mailing list does not allow attachments, just FYI.
--
https://mail.python.org/mailman/listinfo/python-list

[dn]

Post by Michael Torrie

Post by marc nicole
the diagram is also attached here

This text-only mailing list does not allow attachments, just FYI.

Many devs use Markdown (or similar) text-only file-formats for technical
documentation. A tool for including block-graphics in these is "Mermaid"
(https://mermaid.js.org/intro/).

[dn]

Post by marc nicole
Hello community,
I have created a Python code where a main algorithm uses three different
modules (.py) after importing them.
To illustrate and describe it I have created the following component
diagram?
[image: checkso.PNG]
Could it be improved for better description and readability?

Possibly - so little detail as to topic and any hints in the diagram
redacted! What messages do you want to communicate with this diagram?

Given that the three modules are subordinate contributors to the
script/algorithm, place the three modules inside a larger "Algorithm" shape.

[marc nicole]

I want to convey the idea that main.py (main algorithm) imports 3 modules
(V, S, M) (each of them containing .py scripts related to
different functionalities) and use their methods accordingly as per the
requirement: basically the structure of my code and how the modules relate
to each other.

Post by dn

Post by marc nicole
Hello community,
I have created a Python code where a main algorithm uses three different
modules (.py) after importing them.
To illustrate and describe it I have created the following component
diagram?
[image: checkso.PNG]
Could it be improved for better description and readability?

Possibly - so little detail as to topic and any hints in the diagram
redacted! What messages do you want to communicate with this diagram?
Given that the three modules are subordinate contributors to the
script/algorithm, place the three modules inside a larger "Algorithm"
shape.
--
Regards,
=dn
--
https://mail.python.org/mailman/listinfo/python-list

[marc nicole]

The full python package (pypi) being represented as the outermost frame
here including the 4 sub-frames)

Post by marc nicole
I want to convey the idea that main.py (main algorithm) imports 3 modules
(V, S, M) (each of them containing .py scripts related to
different functionalities) and use their methods accordingly as per the
requirement: basically the structure of my code and how the modules relate
to each other.

Post by dn

Post by marc nicole
Hello community,
I have created a Python code where a main algorithm uses three different
modules (.py) after importing them.
To illustrate and describe it I have created the following component
diagram?
[image: checkso.PNG]
Could it be improved for better description and readability?

Possibly - so little detail as to topic and any hints in the diagram
redacted! What messages do you want to communicate with this diagram?
Given that the three modules are subordinate contributors to the
script/algorithm, place the three modules inside a larger "Algorithm"
shape.
--
Regards,
=dn
--
https://mail.python.org/mailman/listinfo/python-list

[Thomas Passin]

Post by marc nicole
The full python package (pypi) being represented as the outermost frame
here including the 4 sub-frames)

Post by marc nicole
I want to convey the idea that main.py (main algorithm) imports 3 modules
(V, S, M) (each of them containing .py scripts related to
different functionalities) and use their methods accordingly as per the
requirement: basically the structure of my code and how the modules relate
to each other.

As is, the diagram doesn't convey any of that. For example, main.py is
a program, not an algorithm. we can't tell that main.py imports three
modules. They might just as well be internal classes. If you want to
communicate something you need to say or show what that thing is.

This might be close to what you have said (I only show 2 of the 3
modules and I didn't have the page width for the bottom left-hand label) -

------------
| main.py | --implements--> Agorithm A
------------
/ \
imports imports
| |
↓ ↓
--------- --------
| V.py | | S.py | --implements--> Subalgorithm A.2
--------- --------

Post by marc nicole

Post by marc nicole

Post by dn

Post by marc nicole
Hello community,
I have created a Python code where a main algorithm uses three different
modules (.py) after importing them.
To illustrate and describe it I have created the following component
diagram?
[image: checkso.PNG]
Could it be improved for better description and readability?

Possibly - so little detail as to topic and any hints in the diagram
redacted! What messages do you want to communicate with this diagram?
Given that the three modules are subordinate contributors to the
script/algorithm, place the three modules inside a larger "Algorithm"
shape.
--
Regards,
=dn
--
https://mail.python.org/mailman/listinfo/python-list

[George Fischhof]

Post by marc nicole
The full python package (pypi) being represented as the outermost frame
here including the 4 sub-frames)

Post by marc nicole
I want to convey the idea that main.py (main algorithm) imports 3 modules
(V, S, M) (each of them containing .py scripts related to
different functionalities) and use their methods accordingly as per the
requirement: basically the structure of my code and how the modules

relate

Post by marc nicole
to each other.

Post by dn

Post by marc nicole
Hello community,
I have created a Python code where a main algorithm uses three

different

Post by marc nicole

Post by dn

Post by marc nicole
modules (.py) after importing them.
To illustrate and describe it I have created the following component
diagram?
[image: checkso.PNG]
Could it be improved for better description and readability?

Possibly - so little detail as to topic and any hints in the diagram
redacted! What messages do you want to communicate with this diagram?
Given that the three modules are subordinate contributors to the
script/algorithm, place the three modules inside a larger "Algorithm"
shape.
--
Regards,
=dn
--
https://mail.python.org/mailman/listinfo/python-list

--
https://mail.python.org/mailman/listinfo/python-list

Hi,

also there are some tools which can generate class hierarchy diagram from
code.
for example here is a post
https://stackoverflow.com/questions/77421030/how-to-generate-the-uml-diagram-from-the-python-code

pyreverse is now part of pylint if I remember well.

BR
George

[Thomas Passin]

Post by marc nicole
it is here https://i.sstatic.net/ykk5Wd0w.png

This diagram does not make much sense to me:

1. What is the purpose of the diagram and who is it intended for?
2. A module and an algorithm are different kinds of things, yet they are
connected together as if they are the same.
3. Connecting lines should always be labeled, preferably with direction
indicators that augment the labels. Otherwise the viewer has to imagine
what the nature of the connection is.
4. It's better if different kinds of things look different. That could
be a different box shape, a different color, or some other visual
difference. Here I am thinking about the box labeled "Algorithm". We
can't tell if it is intended to mean "A library module that implements a
certain algorithm", "An algorithm that the three components cooperate to
implement", "The top-level module for computing an algorithm that
contains three modules", or something else.

[marc nicole]

the purpose of the diagram is to convey a minimalistic idea about the
structure of the code/implementation/software

Le mer. 25 déc. 2024 à 01:49, Thomas Passin via Python-list <

Post by Thomas Passin

Post by marc nicole
it is here https://i.sstatic.net/ykk5Wd0w.png

1. What is the purpose of the diagram and who is it intended for?
2. A module and an algorithm are different kinds of things, yet they are
connected together as if they are the same.
3. Connecting lines should always be labeled, preferably with direction
indicators that augment the labels. Otherwise the viewer has to imagine
what the nature of the connection is.
4. It's better if different kinds of things look different. That could
be a different box shape, a different color, or some other visual
difference. Here I am thinking about the box labeled "Algorithm". We
can't tell if it is intended to mean "A library module that implements a
certain algorithm", "An algorithm that the three components cooperate to
implement", "The top-level module for computing an algorithm that
contains three modules", or something else.
--
https://mail.python.org/mailman/listinfo/python-list

[dn]

Post by marc nicole
I want to convey the idea that main.py (main algorithm) imports 3
modules (V, S, M) (each of them containing .py scripts related to
different functionalities) and use their methods accordingly as per the
requirement: basically the structure of my code and how the modules
relate to each other.
the purpose of the diagram is to convey a minimalistic idea about the
structure of the code/implementation/software

In which case, and assuming the "algorithm" is the application's script,
what will the diagram say that is not conveyed by the three import
statements which (almost) head-up the script?

The difficulty you are presenting to respondents (and to eventual
readers) is the paucity of information: block-labels, line/arrow labels,
diagram title, expected reader(s), ...


PS would it be better to keep the conversation to one Discussion List?

Post by marc nicole
Le mer. 25 déc. 2024 à 01:49, Thomas Passin via Python-list <

Post by Thomas Passin

Post by marc nicole
it is here https://i.sstatic.net/ykk5Wd0w.png

1. What is the purpose of the diagram and who is it intended for?
2. A module and an algorithm are different kinds of things, yet they are
connected together as if they are the same.
3. Connecting lines should always be labeled, preferably with direction
indicators that augment the labels. Otherwise the viewer has to imagine
what the nature of the connection is.
4. It's better if different kinds of things look different. That could
be a different box shape, a different color, or some other visual
difference. Here I am thinking about the box labeled "Algorithm". We
can't tell if it is intended to mean "A library module that implements a
certain algorithm", "An algorithm that the three components cooperate to
implement", "The top-level module for computing an algorithm that
contains three modules", or something else.
--
https://mail.python.org/mailman/listinfo/python-list