Sometimes, code is hard to read due to being optimized. In that case, it's often easier to read a short comment than having to parse the code. // p.xyz += f.

Sometimes, code is hard to read due to being optimized. In that case, it's often easier to read a short comment than having to parse the code. // p.xyz += f.xyz * timeStep __m128 ts = _mm_load1_ps(&timeStep); __m128 x, y, z; __m128 fx, fy, fz; for(int i = 0; i < NUM_PARTICLES; i+=4) { x = _mm_load_ps(px + i); y = _mm_load_ps(py + i); z = _mm_load_ps(pz + i); fx = _mm_load_ps(pfx + i); fy = _mm_load_ps(pfy + i); fz = _mm_load_ps(pfz + i); x = _mm_add_ps(_mm_mul_ps(fx, ts), x); y = _mm_add_ps(_mm_mul_ps(fy, ts), y); z = _mm_add_ps(_mm_mul_ps(fz, ts), z); _mm_store_ps(px + i, x); _mm_store_ps(py + i, y); _mm_store_ps(pz + i, z); } Sometimes, it's because you're doing something that looks surprising, but is there for some reason, so that the next time someone looks at that code, they know why something is done in that fashion. val loginForm = Form( tuple( "email" -> text, "password" -> text, "rememberMe" -> optional(text) // jfim: HACK For some reason, having this as boolean causes a None.get in Play 2.1.0 ) ) Comments should be there to explain why the code does something or what it does in a more readable fashion(because it's faster to read plain English than code), neither of which can be covered by tests.