improve documentation and style
prepare for collision detection