scores: documentation and refactoring