add many comments and fix a minor layout 'issue' (it actually worked before, but it was very bad, same name used twice in same scope)