What are the best practices for using comments in publicly viewable email HTML code?
Michael Ko
Co-founder & CEO, Suped
Published 20 May 2025
Updated 19 Aug 2025
7 min read
When building HTML emails, developers often use comments for internal notes, temporary code disabling, or to target specific email clients. Unlike standard website development, where code comments are typically stripped or minified before deployment to a live environment, comments in HTML emails usually remain publicly viewable within the recipient's email client.
This means that any information left in your email HTML comments can be seen by anyone who views the email's source code. While this might seem like a minor detail, it introduces unique considerations regarding security, file size, and email client rendering.
Understanding how to manage these comments effectively is crucial for maintaining both the integrity of your code and the performance of your email campaigns. Let's explore the best practices for using comments in publicly viewable email HTML.
The purpose of HTML comments in email
HTML comments, denoted by <!-- comment text -->, are primarily used to add explanatory notes within the code. They help developers understand complex sections, track changes, or temporarily comment out code that is not needed for the current version. For standard web pages, these comments are often removed during the build process, preventing them from being seen by end-users or affecting performance.
In email development, comments take on an additional role, particularly with conditional comments. These are special comments recognized by certain email clients, like Outlook (specifically older desktop versions), to apply specific CSS styles or HTML elements that resolve rendering quirks. Without these, achieving consistent layouts across all clients would be even more challenging.
Despite their utility, the fact that these comments remain visible in the final email code necessitates a careful approach. While standard browsers simply ignore HTML comments and don't render them, email clients vary in their handling. Some might process them in unexpected ways, while others expose them directly to anyone inspecting the email's source.
Security and performance considerations
One of the most significant concerns with publicly viewable HTML comments is the potential for security vulnerabilities. Developers might inadvertently leave sensitive information, such as API keys, internal network paths, or even placeholders for credentials, within comments. While these are meant for internal use, their exposure in the email's source code can be exploited by malicious actors, leading to data breaches or other security incidents. It's a fundamental principle of secure coding practices to ensure no sensitive data is present in client-side code.
Additionally, comments contribute to the overall file size of your email. While a few lines of comments might not seem like much, in large, complex email templates, they can add up, increasing the email's payload. Larger email sizes can negatively impact loading times, especially on slower connections or mobile devices. Some email clients (like Gmail) clip messages that exceed a certain size, potentially hiding important content from your recipients.
Security warning: data exposure
Never include sensitive information (e.g., login credentials, API keys, internal system details) in HTML comments within your email code. These comments are easily visible to recipients who view the email source, creating a significant security risk. A strong build process should always strip out non-essential comments before deployment.
Furthermore, there's the question of whether commented code in emails affects spam filters and deliverability. While benign comments are unlikely to trigger spam filters, overly verbose or suspicious-looking comments (e.g., those containing keywords often associated with spam) could potentially contribute to a higher spam score. It's generally a best practice to keep your email HTML as clean and concise as possible to avoid any unintended deliverability issues.
Example of sensitive data in a commenthtml
<!-- Important: Do not remove this comment; contains internal tracking ID for analytics: USER_ID_12345 -->
Email client compatibility and rendering
Email client compatibility is a notorious challenge in email development. Unlike web browsers that largely adhere to web standards, email clients often have their own rendering engines and interpretations of HTML and CSS. This leads to inconsistencies in how emails display. Conditional comments were introduced as a workaround for specific rendering issues, particularly with Microsoft Outlook, allowing developers to target different versions of the client with tailored code.
However, using too many or improperly formatted comments can introduce new rendering problems. While <!-- --> comments are generally ignored by most modern email clients, overly complex or malformed HTML structures, even when commented out, can sometimes lead to unexpected visual glitches or affect the layout. This underscores the importance of writing clean, valid HTML. Learn more about how malformed HTML impacts email deliverability.
To ensure your emails render as intended across the wide array of email clients, thorough email testing is non-negotiable. Testing tools can simulate how your email appears in different environments, helping you identify and fix rendering issues before they reach your subscribers. This includes verifying how comments, especially conditional ones, are processed (or ignored) by each client.
Comment type
Purpose
Suitability for email HTML
<!-- -->
General HTML comments (developer notes, temporary code disabling)
Generally safe if minimal, but avoid for publicly viewable code unless stripped. Can add to file size.
<!--[if IE]...<![endif]-->
Conditional comments (target Outlook specific rendering)
Essential for cross-client compatibility, but use sparingly and only when necessary for specific client fixes.
Best practices for email HTML comments
The overarching best practice for comments in publicly viewable email HTML is to minimize them. Ideally, your production email code should contain only what's absolutely necessary for rendering and functionality. If a comment isn't serving a crucial role in client compatibility (like a conditional comment) or temporary debugging, it should be removed.
When comments are unavoidable, keep them concise and to the point. For instance, conditional comments are often essential for ensuring proper rendering in older Outlook versions, so these are a valid exception. However, even these should be implemented cleanly and without excessive internal notes that are not directly related to their function.
Recommended practices
Minify code: Use a build process to strip all non-essential comments before sending emails.
Conditional comments: Only use them for specific email client fixes, like Outlook rendering issues.
Separate concerns: Keep extensive developer notes and documentation in your source control system, not in the production HTML.
Practices to avoid
Sensitive data: Never include credentials, API keys, or proprietary information in comments.
Over-commenting: Avoid verbose or unnecessary comments that increase file size and clutter the code.
Broken links: Ensure no broken links exist, even in commented-out sections. Find out if a broken link in a comment affects deliverability.
Ultimately, the best approach is to implement a robust development and deployment workflow. This should include processes for minifying your email HTML, which automatically strips out comments and unnecessary whitespace. By doing so, you minimize file size, reduce potential security risks, and ensure that your publicly viewable email code is as clean and performant as possible, helping you achieve better email deliverability.
Views from the trenches
Best practices
Use version control for detailed change logs and explanations, keeping them out of production email HTML.
Always minify your final email HTML before deployment to automatically remove most comments and whitespace.
Prioritize clear, self-documenting code over excessive comments in your email templates.
Utilize conditional comments only when absolutely necessary for specific email client rendering issues.
Common pitfalls
Leaving sensitive internal project notes or incomplete thoughts in publicly viewable email HTML.
Assuming that email clients will uniformly ignore all types of HTML comments without affecting rendering.
Forgetting to integrate a minification step into your email deployment workflow.
Relying on comments to fix complex rendering issues instead of robust HTML/CSS structure.
Expert tips
Consider using CSS preprocessors that can strip comments automatically during compilation for a cleaner output.
For complex email templates, maintain a separate internal documentation system for detailed code explanations.
Regularly review your email's source code to catch any inadvertently included sensitive data or excessive comments.
Treat email HTML with the same security rigor as any other publicly accessible code base.
Expert view
Expert from Email Geeks says publicly viewed code should ideally have minimal comments, as there's often no functional reason for them to be present in the final output.
December 20, 2017 - Email Geeks
Marketer view
Marketer from Email Geeks says the only valid exception for keeping comments in HTML is when they explain the 'why' behind a specific coding decision.
December 20, 2017 - Email Geeks
Final thoughts on email HTML comments
While HTML comments serve a valuable purpose in code organization and maintenance during development, their role in publicly viewable email HTML is significantly diminished, and in some cases, detrimental. The primary takeaway is to be highly judicious about what remains in your final email code.
Always prioritize a lean, clean codebase free of sensitive information. Leverage build processes to minify your email HTML, stripping out unnecessary comments that could inflate file size or inadvertently expose internal details. For email-specific hacks like conditional comments, ensure they are precise and well-tested across clients.
By adhering to these best practices, you can ensure your email campaigns are not only visually appealing but also secure, performant, and optimized for maximum deliverability.
Outlook (specifically older desktop versions), to apply specific CSS styles or HTML elements that resolve rendering quirks. Without these, achieving consistent layouts across all clients would be even more challenging.
Gmail) clip messages that exceed a certain size, potentially hiding important content from your recipients.
Outlook specific rendering)
