Improve readability and inline documentation in shared utility modules

[eneskemalergin]

Summary

The shared Python utilities are functional, but a readability pass would make them easier for others in the lab to understand and maintain.

Tasks

• improve docstrings where they are unclear or inconsistent
• remove dead or placeholder code where safe
• add concise comments only where logic is hard to follow

Acceptance criteria

• the touched utility functions are easier to read without changing behavior
• static checks still pass after cleanup

Why this matters

This is a low-risk maintenance task that improves onboarding for future contributors.