Add names to parameters on function-calls for easier understanding

[Urfoex]

As pointed out in Code reviews, some function-calls could benefit from having parameters be named.
#38
#41

Identify function-calls, that benefit from having their parameters be named, and adjust them.

Gemini:

For function calls in Python, you should use named arguments (also called keyword arguments) whenever it improves clarity and readability. This is especially true for arguments that are boolean flags, optional with default values, or when a function takes multiple arguments of the same type.

While IDEs provide helpful hints during development, relying on them is a drawback during code review, as you've noted. Code should be understandable on its own, and explicit named arguments are a key part of that.

---

When to Use Named Arguments

Here are the key scenarios where using named arguments is a best practice:

1. For Boolean Flags

This is one of the most important use cases. A bare True or False in a function call is often meaningless without context.

• ❌ Unclear: process_data(my_data, True, False)
• ✅ Clear: process_data(my_data, overwrite=True, recursive=False)

2. For Optional Arguments with Default Values

When a function has multiple optional arguments, it's often unclear which ones you're providing if you use their position.

• ❌ Unclear: create_user("test", "pw123", "Test User", "Admin")
• ✅ Clear: create_user("test", "pw123", full_name="Test User", role="Admin")

3. For Functions with Many Arguments

When a function signature is long, named arguments act as documentation, making the call much easier to understand.

• ❌ Hard to Read: send_email("to@a.com", "from@b.com", "cc@c.com", "Subject", "Body", "attachment.pdf")
• ✅ Easy to Read: send_email(to="to@a.com", from_addr="from@b.com", cc="cc@c.com", subject="Subject", body="Body", attachment="attachment.pdf")

---

Addressing Your Concerns

• Extra Work vs. Readability: The "extra work" of typing argument names is a small, one-time cost. The benefit is long-term readability for everyone who ever has to read or review that code, including your future self. Clarity always wins over brevity.
• Refactoring: Your point about refactoring is valid. If you rename a parameter in a function definition, you must also rename it in all the places it's called with a named argument. However, this is a good thing! It forces you to be aware of the change and its impact. Modern IDEs make this a trivial, automated refactoring task (usually Shift+F6). It also protects you: if the order of parameters changes but the names don't, your code with named arguments will still work correctly, while code relying on position would break silently and catastrophically.

Conclusion: Don't rely on your IDE to make your code readable. Write explicit, clear code for the benefit of human reviewers. Using named arguments is a crucial Pythonic practice that makes your code more robust, easier to read, and self-documenting.