Again both perspective have good reasons, I agree with @anserran that if you need to add this javadoc the code is shitty period. But if it is needed to keep this code as is (at least for some time) I agree with @jtorrente that needs to be documented, maybe not so detailed but the rationale behind should be documented (excluding obvious documentation like "this is a scene list")