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

    From Stefan Ram@21:1/5 to marc nicole on Tue Dec 24 17:35:32 2024
    marc nicole <mk1853387@gmail.com> wrote or quoted:
    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()

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From dn@21:1/5 to Michael Torrie via Python-list on Wed Dec 25 09:49:03 2024
    On 25/12/24 08:00, Michael Torrie via Python-list wrote:
    On 12/24/24 10:27 AM, marc nicole via Python-list wrote:
    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/).

    --
    Regards,
    =dn

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From dn@21:1/5 to marc nicole via Python-list on Wed Dec 25 09:46:43 2024
    On 25/12/24 06:27, marc nicole via Python-list wrote:
    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

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From George Fischhof@21:1/5 to All on Tue Dec 24 23:00:26 2024
    marc nicole via Python-list <python-list@python.org> ezt írta (időpont:
    2024. dec. 24., K 22:09):

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

    Le mar. 24 déc. 2024 à 22:05, marc nicole <mk1853387@gmail.com> a écrit :

    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.

    Le mar. 24 déc. 2024 à 21:56, dn via Python-list <python-list@python.org

    a écrit :

    On 25/12/24 06:27, marc nicole via Python-list wrote:
    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


    --
    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




    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From Thomas Passin@21:1/5 to marc nicole via Python-list on Tue Dec 24 16:44:26 2024
    On 12/24/2024 4:08 PM, marc nicole via Python-list wrote:
    The full python package (pypi) being represented as the outermost frame
    here including the 4 sub-frames)

    Le mar. 24 déc. 2024 à 22:05, marc nicole <mk1853387@gmail.com> a écrit :

    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
    --------- --------

    Le mar. 24 déc. 2024 à 21:56, dn via Python-list <python-list@python.org> >> a écrit :

    On 25/12/24 06:27, marc nicole via Python-list wrote:
    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



    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From Thomas Passin@21:1/5 to marc nicole via Python-list on Tue Dec 24 16:18:54 2024
    On 12/24/2024 3:42 PM, marc nicole via Python-list wrote:
    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.

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From dn@21:1/5 to marc nicole on Thu Dec 26 08:29:53 2024
    On 25/12/24 10:05, marc nicole wrote:
    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.

    On 25/12/24 23:08, marc nicole via Python-list wrote:
    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?



    Le mer. 25 déc. 2024 à 01:49, Thomas Passin via Python-list < python-list@python.org> a écrit :

    On 12/24/2024 3:42 PM, marc nicole via Python-list wrote:
    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.

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


    --
    Regards,
    =dn

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)