improved inline documentation and error handling in common/*