refactor and add comments after peer review with tgloeggl