Why I refuse to give up code comments

I currently teach two different courses that have opposite philosophies behind comments, AP Computer Science Principles in a charter high school and Level 7 Advanced Java Programming at the LEAGUE of Amazing Programmers, a private non-profit volunteer staffed coding school for middle and high schoolers.

The AP course stresses the importance of documentation, both block headers and in line comments. This (https://canvas.instructure.com/courses/943888/pages/adding-c...) typical lesson is par for the course for most curriculums I've seen.

On the other hand our Level 7 curriculum notes say, "Comments: compensate for failure in expressing yourself in code; - a comment is out of date as soon as it’s written - maintenance nightmare - code moves, comments don’t always follow - if something is confusing or disorganized, clean it instead of commenting. cleaning > commenting.

"Exceptions: warning of consequences, explanation of intent, TODOs, copyright, javadocs"

But goes further to test students to use a shortcut in Eclipse to blindly remove all comments from Java code.

The example given in your explanation is particularly troubling as you document calls to method invocations without the context of the surrounding code which should plainly indicate why the method is being invoked. You suggest that the invocation should document the function of the invoked method which is presumptuous and most troubling to me. What if I change the way customers are notified, unless I go edit your comment it's out if date even without other changes in that part of the system. You've undercut your entire argument with, "Yes, a function should only do one thing, and perhaps that's why my example isn't the best."

If a function is written to do one thing then the context should be clear and there shouldn't need to be comments.

Back to the differences between AP CSP (lots of comments) and Level 7 (no comments). The AP CSP course is written for novice programmers writing bad code that will never be used again. They need comments to understand what the code does. In the software craftsmanship course experienced coders are learning to write code for the future using good practices. And they are taught that if they need to add a comment then they need to rethink how the code was written and refactor.

There is one last thing that I want to bring up as I went through this process of coming to terms with comments. We began in the AP class discussing the need to comment changes in the code (bug fixes) to address writing prompts that focus on iteration. I realized that we have resolved the maintaining comments problem in the real world by moving comments into the commit messages in our VCS system. I'm able to see the justification for why a specific line of code has been changed, what it looked like originally and what test cases are relevant. In any decent IDE obtaining the commit message history for a given line of code is a few clicks and when not needed those comments aren't in the way.

At the end of all of this introspection, I realized that I will probably be marking down candidates in technical interviews if they add comments. It's a clear indication that the candidate values the clarity of simple code and understands the concept of encapsulation.

And the logic for not renaming the method is what exactly?

In functional languages, a single filter-map-fold can accomplish what might take half a dozen classes in Java. In those circumstances, a line or two of comments explaining the rough idea of what's happening is essential. You might argue that it's a regression to the bad-old-days of obtuse C, but the power of the paradigm more than makes up for the extra need of documentation.

Also, would you penalize a developer for commenting cleanly written code? No attempt to communicate clearly should ever be discouraged, especially in a discipline so rife with miscommunication as ours.

How? By means of SRP as exemplified in section 4 of http://firstclassthoughts.co.uk/Articles/Readability/Optimal...