In my early days as a developer, I wrote a lot of comments. They were necessary because otherwise I would have quickly lost track of things in my own code: due to limited modularity, large loops with countless instructions, and five-character variable names, orientation without these constant reminders was virtually impossible.
With CleanABAP and its recommendations regarding commenting, things changed dramatically for the better for me. Today, I rarely use comments. When I do, it’s a clear indication that I haven’t been able to express myself clearly enough in the code and that additional information is fundamentally necessary for understanding.
Which brings us to the topic of this blog: for a long time, the focus was on ensuring that both I and other developers could understand code. Now, however, it’s also about enabling AI to grasp the context of code, and that’s no trivial task. Comments make this task even more challenging.
While the syntax of code follows the rules of the respective programming language, comments are like a testing ground for free-for-all, because almost anything goes. The chamber of horrors of absurd comment abuse knows almost no bounds, as I’ve already reported on this blog.
Basically, one can identify a wide variety of problems with comments. Here are a few examples:
- They are written in some natural language. Wikipedia mentions approximately 7,000 languages used worldwide in this article.
- They use a shortened spelling compared to the standard spelling of a language.
- They contain technical and specialized terms that the original development team invented for better internal communication, but which no one outside that team knows.
- They document something that the code already adequately states.
- They contradict the logic derived from the code because they are incorrect or outdated.
- They have nothing to do with the logic derived from the code.
- They themselves consist of old statements that were commented out to make them ineffective.
These problems are already major challenges for humans. I guess they’re even more problematic for AI.
Sure, one could say AI ignores every comment. But that could mean missing valuable contextual information. On the other hand, the only remaining option is the arduous task of thoroughly examining each comment and, based on the results, including or excluding it from the context, just as a human reader would have to do.
As a middle ground, the CleanABAP recommendation regarding comments remains: express as little as necessary in comments, as much as possible in the source code.
I guess AI analyzing code would be significantly easier due to the clear rules of a programming language. Not to mention that we’ve had extensive experience interpreting source code and preparing it for machine use since the early days of computer science, long before we had AI. I’m talking about compiler and interpreter construction.
Furthermore, there’s another crucial advantage for me that comes from using code instead of comments. You can test code using unit tests. Unless it involves generating a truly random number, most everyday code that we ABAP developers write can probably even be reliably tested deterministically.
While writing this, another advantage just occurred to me. With sufficient modularization, code is reusable. This even reduces the potential temptation to insert comments – less code, less risk.
Thank you for reading. If you enjoyed the post, please share the article with your community. Thanks in advance.
Michael (a mind forever voyaging)