From 14a63debe2cd81585cc98dfcf42af6ee0c07c3d1 Mon Sep 17 00:00:00 2001 From: uzyfabbargama Date: Mon, 3 Aug 2026 23:59:13 -0300 Subject: [PATCH] Introduce PEP 1234 for block comments in Python This PEP proposes a new syntax for block comments in Python using `#"""` and `##"""` delimiters. It aims to provide a consistent and efficient way to comment and uncomment code blocks, addressing the lack of native block comment syntax in Python. --- peps/pep-1234.rst | 221 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 221 insertions(+) create mode 100644 peps/pep-1234.rst diff --git a/peps/pep-1234.rst b/peps/pep-1234.rst new file mode 100644 index 00000000000..bdb3616dca0 --- /dev/null +++ b/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 +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.