diagnostics - refactoring + comments