more comments and minor improvements for the controllers