PEP NNN: block comments in Python

peps/pep-1234.rst

@@ -0,0 +1,221 @@
+PEP: 1234
+Title: Block Comments for #-Based Languages While Preserving Python Standard Syntax
+Author: Anonymous Python Enthusiast <email@example.com>
+Sponsor: Pending
+PEP-Delegate: Pending
+Discussions-To: Pending
+Status: Draft
+Type: Standards Track
+Topic: Release
+Requires: 
+Created: 03-Aug-2026
+Python-Version: 3.14
+Post-History: Pending
+Replaces:
+Superseded-By:
+Resolution:
+
+Abstract
+========
+
+This PEP proposes a new syntax for block comments in Python using the
+`#"""` and `##"""` delimiters, providing a consistent and efficient way
+to comment and uncomment code blocks.
+
+The proposal introduces a semantic extension to the existing `#` comment
+system, allowing developers to toggle between line comments and block
+comments with minimal editing effort (just one character: `#` ↔ `##``).
+
+No major programming language that uses `#` for line comments (Python,
+Ruby, Perl, Bash, etc.) has a native block comment syntax that
+maintains consistency with its line comment system. This PEP addresses
+that gap.
+
+Motivation
+==========
+
+Current Python only supports single-line comments with `#`. Developers
+often use triple-quoted strings (``"""``) as a hack for block comments,
+which is semantically incorrect and confuses tools (linters, IDEs,
+docstring extractors).
+
+This practice violates the Zen of Python principles:
+- "Explicit is better than implicit" (a hack is implicit)
+- "Special cases aren't special enough to break the rules"
+
+This PEP introduces a proper block comment syntax that:
+- Uses the existing `#` prefix (consistent with line comments)
+- Uses ``"""`` as block delimiter (familiar to Python developers)
+- Allows easy toggling between block and line comments
+- Does not conflict with docstrings or existing syntax
+- Requires only ONE character change to toggle modes
+
+Specification
+=============
+
+1. A block comment starts with `#"""` and ends with `#"""`
+2. Everything between these delimiters is ignored by the parser
+3. `##"""` is treated as a normal line comment (NOT a block comment)
+4. Nested block comments are NOT supported (by default)
+5. Block comments can be used anywhere a line comment can
+6. The parser evaluates from left to right, so `#` always takes precedence
+
+Parser Behavior
+---------------
+
+The Python parser would handle tokens as follows:
+
+==========  ==========================  =======================
+Syntax      Parser Interpretation       Result
+==========  ==========================  =======================
+`#`         Line comment                Ignore until newline
+`#"""`      Block comment start         Ignore until `#"""`
+`##"""`     `#` + `#"""`                Normal line comment
+`###"""`    `##` + `#"""`               Normal line comment
+==========  ==========================  =======================
+
+This behavior is consistent with Python's existing lexer design, where
+`#` initiates a comment and all subsequent characters are treated as
+part of the comment until a newline or delimiter.
+
+Examples
+--------
+
+Basic block comment::
+
+    #"""
+    This is a block comment
+    It can span multiple lines
+    And is semantically correct
+    #"""
+
+Toggling between block and line comments::
+
+    #""" VERSION A (active)
+    def process(data):
+        return data * 2
+    #"""
+
+    ##""" VERSION B (commented out - line comment mode)
+    def process(data):
+        return [x * 2 for x in data]
+    ##"""
+
+    # To activate VERSION B, simply change #""" to ##""" and vice versa
+    # This requires editing only 2 lines (the delimiters), not the entire code
+
+Rationale
+=========
+
+This proposal addresses a common pain point in Python development while
+maintaining the language's philosophy of being explicit, readable, and
+consistent. The proposed syntax:
+
+1. Follows the principle of least surprise: `#` means comment, and
+   ``"""`` means multi-line, so `#"""` means multi-line comment
+2. Is composable: developers already know both components
+3. Is distinctive: visually different from docstrings
+4. Is practical: solves real-world problems
+
+Backwards Compatibility
+=======================
+
+This proposal is fully backwards compatible because:
+- `#"""` is currently not a valid syntax (it's a line comment)
+- No existing code uses `#"""` as a comment (it would just be ignored)
+- Docstrings (``"""``) are unaffected unless preceded by `#`
+- The parser's left-to-right evaluation ensures `#` always wins
+
+Transition plan:
+- Phase 1: PEP acceptance, no changes to existing code required
+- Phase 2: Linters and IDEs update to recognize new syntax
+- Phase 3: Community adoption through documentation and tutorials
+
+Security Implications
+=====================
+
+This feature introduces no new security vulnerabilities. The block
+comment syntax is processed entirely at the lexical analysis stage,
+before any code execution. A malicious user cannot exploit block
+comments to execute arbitrary code or bypass security controls.
+
+However, as with any commenting mechanism, developers should be cautious
+about leaving sensitive information (passwords, API keys) in comments
+that might be committed to version control. This is a pre-existing
+concern not specific to this proposal.
+
+How to Teach This
+=================
+
+The new syntax is intuitive and can be taught alongside existing
+comment syntax:
+
+1. **Line comments**: Use `#` for single lines
+2. **Block comments**: Use `#"""` ... `#"""` for multiple lines
+3. **Toggle mode**: Add/remove one `#` to switch between modes
+
+Documentation should emphasize:
+- Block comments are real comments (not strings)
+- The `#` prefix makes them visually distinct from docstrings
+- The `##"""` syntax is for line comments containing triple quotes
+
+Reference Implementation
+========================
+
+A proof-of-concept implementation would require modifications to the
+CPython lexer:
+
+1. Add recognition of `#"""` as a block comment start token
+2. Skip all tokens until `#"""` is found (or EOF)
+3. Treat `##"""` as a normal line comment (existing behavior)
+4. Ensure compatibility with existing tokenization rules
+
+Estimated implementation effort: 1-2 person-weeks. A prototype could be
+developed as a fork of CPython.
+
+Rejected Ideas
+==============
+
+1. **Using `/* */` syntax**: Rejected because it's inconsistent with
+   Python's `#` comment system and would add a completely new syntax.
+
+2. **Using `#` only without delimiters**: Rejected because it would
+   require escaping newlines and would be less readable.
+
+3. **Using triple quotes without `#`**: Rejected because this is the
+   current hack that this PEP aims to replace.
+
+4. **Using `#region` / `#endregion`**: Rejected because it's
+   IDE-specific and not a language-level feature.
+
+Open Issues
+===========
+
+1. Should nested block comments be supported? Currently proposed as NOT
+   supported, but could be added in a future PEP.
+
+2. How should block comments interact with string literals? The parser
+   should respect string boundaries; `#"""` inside a string should not
+   start a block comment.
+
+3. Should `##"""` be the only way to escape, or should `###"""` also
+   work? Currently treating all `##*"""` as line comments.
+
+Acknowledgements
+================
+
+Thanks to the Python community on Reddit and the python-dev mailing
+list for early feedback and discussion of this proposal.
+
+Footnotes
+=========
+
+.. _PEP 8: https://peps.python.org/pep-0008/
+.. _PEP 20: https://peps.python.org/pep-0020/
+.. _Python Language Reference: https://docs.python.org/3/reference/lexical_analysis.html
+
+Copyright
+=========
+
+This document is placed in the public domain or under the
+CC0-1.0-Universal license, whichever is more permissive.