more comments, improved methods parameters