reduce cyclomatic complexity and enhance docstrings