Cybersecurity
January 28, 2025

Secure Code Comments: Empowering Developer-led Application Security Culture

long exposure image of man walking by blue panels

The Overlooked Power of Secure Code Comments in Application Security

Secure code comments are an often overlooked aspect of application security (AppSec). While traditional code comments focus on explaining the code's functionality, security-focused comments are crucial to promoting secure coding practices throughout the development lifecycle (SDLC). 

Let's explore how integrating security comments into your organization’s code can benefit both developers and security professionals—enabling key company goals.

Understanding the Importance of Secure Coding Practices

Perhaps you already have some opinion on source code comments. You may be a staunch believer that code should be self-documenting and comments are a crutch for poor code. You may be ‘all in’ on comments.
But how often do you think about security in the context of code comments? 

According to a recent study, almost half of the code of GitHub software projects analyzed contained references to Common Vulnerability Enumeration (CVE) IDs. That’s an indicator that developers are applying a fix to an already-found vulnerability. That’s a retroactive approach to application security. The study also found that less than 4% of comments used Common Weakness Enumeration (CWE) IDs to proactively identify threats. This means that most developers wait for weaknesses in their applications to be exploited by adversaries before defending against them.

The Role of Security-Focused Comments

The closer you can embed application security practices into a developer’s workflow, the more likely they are to make it a habit, helping to underpin a security-oriented culture shift.

So, what better way to think about security proactively than through comments? Senior developers and application security champions can quickly and effectively educate other developers about best practices without leaving the comfort of their Integrated Development Environment (IDE).

Best practice for code comments suggests emphasizing the why, not the what. Security-focused comments are no different. Meanwhile, they play a crucial role in promoting secure coding practices, enabling teams to:

  • Document application security decisions: Explaining the rationale behind specific security measures, such as input validation, encryption, and access control mechanisms.
  • Highlight potential vulnerabilities: Drawing attention to areas of code that may be susceptible to attacks, such as SQL injection, cross-site scripting (XSS), and unprotected data.
  • Foster security standards and best practices: Enhancing developer understanding by linking to relevant security standards, guidelines, and resources and facilitating efficient code reviews.

Example: Enhancing Code with Security Comments

Let’s consider a simplified Python function, which performs a simple insert operation into a database:

As you can see, in addition to the regular docstring, we succinctly mention why we’re using parameterized queries over string concatenation. We also reference a CWE and provide a link for anyone who wants to learn more. 

With just three extra sentences in a function comment, we’ve given less experienced developers who are code spelunking a quick lesson (or reminder) about why and how to prevent SQL injection.

Better yet, any security engineer performing a secure code review will be much more confident that their developer understands why they chose to write the code the way they did. This knowledge, in turn, expedites that coveted ‘approve’ on their pull request, reducing the time to get the code safely into production. 

Beyond Code Comments: Empowering Developers Through AppSec Training

Code comments are a valuable AppSec tool but are only one piece of the puzzle. To cultivate a developer-led security culture, organizations should invest in comprehensive training programs that empower developers with the knowledge and skills to build secure applications from the ground up.

Using safe, real-world scenarios and interactive exercises, modern hands-on training programs are critical for developing practical security skills. Developers learn by doing, leveraging a new understanding of the attacker's point of view and working to fix code in real applications. In effect, they master secure coding practices as part of their workflow—saving time while boosting your security posture.

Final Thought: Cultivating a Developer-led AppSec Culture

Organizations can create powerful synergy by combining the power of security-focused comments with comprehensive training programs that make it easy for developers to become part of your defense team. Documenting their understanding of AppSec best practices through well-crafted security comments is just one example, and it’s a good one. 

Such an iterative process reinforces application security knowledge and fosters a continuous learning environment within the development team. Better still, code not only ships faster, it's also more secure.

To learn more, check out our practical ebook: 6 Steps for Navigating Secure Development in Today’s Landscape

Trusted by top companies worldwide
to enhance cybersecurity

What Our Customers
Are Saying About Immersive

Realistic simulation of current threats is the only way to test and improve response readiness, and to ensure that the impact of a real attack is minimized. Immersive’s innovative platform, combined with Kroll’s extensive experience, provides the closest thing to replication of a real incident — all within a safe virtual environment.

Paul Jackson
Regional Managing Director, APAC Cyber Risk, Kroll

Ready to Get Started?
Get a Live Demo.

Simply complete the form to schedule time with an expert that works best for your calendar.