There is a long-standing debate in the software development community regarding the necessity of comments. The argument often suggests that if a developer follows best practices—using clear, descriptive variable names and logical function names—the code becomes “self-documenting.” Under this philosophy, comments are viewed as redundant or even a sign of bad code.
However, this perspective overlooks a fundamental truth: code is written for computers, whereas comments are written for humans. While clean syntax and naming conventions are important, they rarely convey the full context, intent, or logic required for effective security and maintenance.
The Human Element of Coding
Writing code that compiles is only half the battle; writing code that can be understood by others is the true challenge. Even with perfect naming conventions, code is ultimately a set of logic instructions for a machine. It does not naturally read like English prose.
Cognitive load increases significantly as functions grow in size. Once a function exceeds just a few lines of code, or involves complex logic, the human brain has to work much harder to parse what is happening. A well-placed comment acts as a signpost, allowing a developer to understand the “why” and the “what” without having to mentally trace every variable assignment and loop.
Comments as Documentation and Disaster Recovery
Comments should be viewed as an essential form of documentation. Like all documentation, there is a small initial investment of time required to write and maintain them. However, this investment yields significant returns in the future.
When a critical bug arises or a security vulnerability needs to be patched, time is of the essence. Rather than spending valuable hours trying to decipher the original author’s intent, comments allow for faster understanding and quicker remediation. This is particularly vital for disaster planning and handover processes. If a key developer leaves the organisation, their code should not remain a mystery to the rest of the team. Comprehensive comments ensure that knowledge is shared and that the organisation is not reliant on a single individual’s memory.
The Impact of AI and “Vibe Coding”
The rise of Artificial Intelligence in software development has shifted the landscape, but it has not removed the need for comments. In fact, it has arguably made them more important.
We are entering an era of “vibe coding,” where natural language prompts are used to generate code. in this context, the prompt itself acts as a high-level comment. Furthermore, AI tools rely on context to function effectively. Clear comments help AI assistants understand the existing codebase, ensuring that any suggested additions or changes remain aligned with the overall logic and structure.
Additionally, modern AI coding tools have removed the excuse that writing comments is “too time-consuming.” specific AI tools can now analyse code and generate explanatory comments automatically. This means that maintaining high-quality documentation is easier than ever before.
A Mandatory Practice for Security
At Vertex, we believe that clarity is a component of security. Obscure or difficult-to-read code is a hiding place for vulnerabilities.
Whether for the benefit of human team members or to assist AI co-pilots, comments are now a mandatory aspect of professional software development. They facilitate better teamwork, easier maintenance, and a more robust security posture.
If you are looking to review your organisation’s secure coding practices or require assistance with your cybersecurity strategy, contact the expert team at Vertex.
Why Code Comments Are Essential in the Age of AI
There is a long-standing debate in the software development community regarding the necessity of comments. The argument often suggests that if a developer follows best practices—using clear, descriptive variable names and logical function names—the code becomes “self-documenting.” Under this philosophy, comments are viewed as redundant or even a sign of bad code.
However, this perspective overlooks a fundamental truth: code is written for computers, whereas comments are written for humans. While clean syntax and naming conventions are important, they rarely convey the full context, intent, or logic required for effective security and maintenance.
The Human Element of Coding
Writing code that compiles is only half the battle; writing code that can be understood by others is the true challenge. Even with perfect naming conventions, code is ultimately a set of logic instructions for a machine. It does not naturally read like English prose.
Cognitive load increases significantly as functions grow in size. Once a function exceeds just a few lines of code, or involves complex logic, the human brain has to work much harder to parse what is happening. A well-placed comment acts as a signpost, allowing a developer to understand the “why” and the “what” without having to mentally trace every variable assignment and loop.
Comments as Documentation and Disaster Recovery
Comments should be viewed as an essential form of documentation. Like all documentation, there is a small initial investment of time required to write and maintain them. However, this investment yields significant returns in the future.
When a critical bug arises or a security vulnerability needs to be patched, time is of the essence. Rather than spending valuable hours trying to decipher the original author’s intent, comments allow for faster understanding and quicker remediation. This is particularly vital for disaster planning and handover processes. If a key developer leaves the organisation, their code should not remain a mystery to the rest of the team. Comprehensive comments ensure that knowledge is shared and that the organisation is not reliant on a single individual’s memory.
The Impact of AI and “Vibe Coding”
The rise of Artificial Intelligence in software development has shifted the landscape, but it has not removed the need for comments. In fact, it has arguably made them more important.
We are entering an era of “vibe coding,” where natural language prompts are used to generate code. in this context, the prompt itself acts as a high-level comment. Furthermore, AI tools rely on context to function effectively. Clear comments help AI assistants understand the existing codebase, ensuring that any suggested additions or changes remain aligned with the overall logic and structure.
Additionally, modern AI coding tools have removed the excuse that writing comments is “too time-consuming.” specific AI tools can now analyse code and generate explanatory comments automatically. This means that maintaining high-quality documentation is easier than ever before.
A Mandatory Practice for Security
At Vertex, we believe that clarity is a component of security. Obscure or difficult-to-read code is a hiding place for vulnerabilities.
Whether for the benefit of human team members or to assist AI co-pilots, comments are now a mandatory aspect of professional software development. They facilitate better teamwork, easier maintenance, and a more robust security posture.
If you are looking to review your organisation’s secure coding practices or require assistance with your cybersecurity strategy, contact the expert team at Vertex.
CATEGORIES
TAGS
SHARE