I am old. I grew up in an age of cryptic Fortran and worse C code that absolutely required comments to be intelligible.
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.
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.
I think you have a bit of a bias coming from Javaland. Java code is incredibly verbose for the sake of allowing the developer a thousand places to write self documenting code. It's a slog to write, but easier to read, by far.
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.
Yes, my son is currently writing a lot of functional code and complaining when I force him to do something in Java. It bothers me that we see the verbosity of Java as a detriment and then say we should add comments to functional languages.
Don't get me wrong, I strongly believe in the appropriate functional approach where it's beneficial, but I strongly believe that it needs to be as self explanatory as Java code, otherwise you get the same staleness problem with the comments that led to the elimination of them initially.
With regards to whether someone should be penalized for extraneous comments, if the comment is necessary then it indicates a code problem. If unnecessary it's subject to becoming out of date or erroneous. So, yes, I stand by my contention that if you add comments to code in the majority of cases you should be penalized.
It took me a long, long time to change my view on this so I understand where people are coming from. I also require my beginning students to comment just so I can try to understand what they are doing so my position is not absolute. But given the choice between a developer who communicates clearly in code and knows it and one who either needs or believes he needs comments I'll choose the first.
> But given the choice between a developer who communicates clearly in code and knows it and one who either needs or believes he needs comments I'll choose the first.
This really just reads to me like you're selecting for hubris over humility, which is not likely to get good results over the long term. Give me a coder who doubts his code any day, over someone overconfident.
I refuse to give up comments too. For personal projects, I prefer to keep comments outside the code as much as possible, in separate documentation files, so I can read more code vertically (no comment folding solution ever fit my needs).
From experience reading my own code and other people's code, it's never "self-documenting".
This trend is a combination of an attempt to nudge developers to take better care of the code so it's less dependent on comments (a good principle, but too optimistic), good old arrogance (this is a great team, no bad code ever gets written here), a fear of judgement (too often the comment will show what the person writing it understands of the code, including parts that are unclear to them).
The previous motivations can be reduced to this: some billion-dollar SV startup must be banning comments in their linter rules. And if some well-funded startup is doing that, everyone must do it too. It's the unwritten overriding law of software development.
I mostly agree with you. I think the key is to always keep improving the code, don't expect or try to achieve perfection, and keep refining your concept of what makes for "improved" code.
So if you come across a method name that does not clarify enough for you what it does, and there are no comments to help, you might start by getting your questions answered, and then add comments that help clarify things. If you stop there, you have done your part, you have improved the code. The next person that comes across it, even if that person is you, is likely to have a better experience than you did. After that, if you still have more time and energy to improve it further, can try to find a better name for that method. After renaming it, you might discover the comment is no longer adding clarity, just duplication. At that point, removing the comment would be further improving the code. But if removing the comment makes it less clear, and if in your opinion the level of clarity added by the comment is worth its weight in screen space and developer read time, then removing it would be making the code worse, so you should leave it there.
I agree with what you say about context in that context is one of the most common things to not be able to express clearly enough in the code itself. However, you can still attempt to do so. An unhelpful comment is what it is, regardless of if it is expressing context or not. The same goes for a helpful comment. Sometimes a comment is helpful when the missing context is why a strange design decision was made in the code, or an unintuitive business problem users deal with that is solved by the logic in the code.
> So if you come across a method name that does not clarify enough for you what it does, and there are no comments to help, you might start by getting your questions answered, and then add comments that help clarify things.
And the logic for not renaming the method is what exactly?
I'm not saying you should not rename it instead. I'm just suggesting that there may be times when placing a helpful comment is easier than renaming it. So you might start by adding a comment, and then consider if you can rename the method to not need the comment. But you are right that if there is an immediately obvious way to rename the method to add clarity, you could just do that and be done.
Good code should be readable and self explanatory. Comments should not focus on explaining the code, but rather present the overall logic.
A good piece of code is one that doesn't need the reader to get into the implementation details.
Commenting code is an art...
Between your Kanban board and your source control repository, there should be plenty enough for code documentation and comments. My engineers are trained to follow 2 basic software engineering priciples: function names should convey specific actions and methods should have a defined scope. Classes should therefore be compact as a result of the previous 2 principles. This keeps comments to a minimum and avoid ambiguities if semantic changes are required.
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.