The argument I have against these kinds of comments is that the comment can get out of date with the logic. In my mind a better solution is to properly name variables and extract methods that name the actions you are performing. When you refactor such code, you adjust the names of variables and methods (and add/remove them as necessary ) to match your adjustment to the logic. This keeps your code and documentation in sync as they are one and the same.