improve method names, add more coding examples, put good example methods after bad ones, add spock style notes