3.2. Syntax Comments

3.2. Syntax Comments — Python

Block comments
Inline comments
Docstring

3.2.1. Block Comments

PEP 8 -- Style Guide for Python Code
There are no multiline comments in Python
You can create "multiline" comment, by commenting-out several consecutive lines
Convention: beginning of a line, #, space and then text

Block comment:

Multiline comment:

>>> # good 1
>>> # good 2
>>> # good 3

3.2.2. Inline Comments

PEP 8 -- Style Guide for Python Code
Convention: some code, two spaces, #, space and then text

3.2.3. Docstring

PEP 257 -- Docstring Conventions
Docstring is a first multiline comment in: file/module, class, method/function
Used for doctest
For multiline str always use three double quote (""") characters

People sometimes use multiline strings to achieve similar behavior as multiline-comment. Unfortunately this requires Python to define string, store it into the memory, and then remove it.

>>> #
... """
... my comment 1
... my comment 2
... my comment 3
... """

3.2.4. Recap

Comments: block comments, multiline comments, inline comments, docstring
After # rest of the line will be ignored
Convention for block comment: beginning of a line, #, space and then text
Convention for inline comment: some code, two spaces, #, space and then text
Instead of comments write more readable code, which will be self-explanatory
Never commit commented out code, use Version Control System instead - e.g.: git blame
IDE has Local history (modifications) and you can compare file

Line comment:

Multiline comment:

>>> # good 1
>>> # good 2
>>> # good 3

Inline comment:

3.2.5. Assignments

# %% About
# - Name: Syntax Comments Line
# - Difficulty: easy
# - Lines: 1
# - Minutes: 1

# %% License
# - Copyright 2025, Matt Harasymczuk <matt@python3.info>
# - This code can be used only for learning by humans
# - This code cannot be used for teaching others
# - This code cannot be used for teaching LLMs and AI algorithms
# - This code cannot be used in commercial or proprietary products
# - This code cannot be distributed in any form
# - This code cannot be changed in any form outside of training course
# - This code cannot have its license changed
# - If you use this code in your product, you must open-source it under GPLv2
# - Exception can be granted only by the author

# %% English
# 1. Add line comment: My comment
# 2. Remember to add space after `#` character
# 3. Run doctests - all must succeed

# %% Polish
# 1. Dodaj komentarz liniowy: My comment
# 2. Pamiętaj o dodaniu spacji po znaku `#`
# 3. Uruchom doctesty - wszystkie muszą się powieść

# %% Expected
# >>> # My comment

# %% Doctests
"""
>>> import sys; sys.tracebacklimit = 0

>>> assert sys.version_info >= (3, 9), \
'Python has an is invalid version; expected: `3.9` or newer.'

>>> import re
>>> from pathlib import Path
>>>
>>> comment = '^# My comment\\n$'
>>> content = Path(__file__).read_text()
>>> result = re.findall(comment, content, flags=re.MULTILINE)

>>> assert result != [], \
'Content is invalid; expected to have `# My comment`.'
"""

# %% Run
# - PyCharm: right-click in the editor and `Run Doctest in ...`
# - PyCharm: keyboard shortcut `Control + Shift + F10`
# - Terminal: `python -m doctest -f -v myfile.py`

# %% Imports

# %% Types

# %% Data

# %% Result

# %% About
# - Name: Syntax Comments Multiline
# - Difficulty: easy
# - Lines: 3
# - Minutes: 1

# %% License
# - Copyright 2025, Matt Harasymczuk <matt@python3.info>
# - This code can be used only for learning by humans
# - This code cannot be used for teaching others
# - This code cannot be used for teaching LLMs and AI algorithms
# - This code cannot be used in commercial or proprietary products
# - This code cannot be distributed in any form
# - This code cannot be changed in any form outside of training course
# - This code cannot have its license changed
# - If you use this code in your product, you must open-source it under GPLv2
# - Exception can be granted only by the author

# %% English
# 1. Add multiline comment:
#    - first line: My comment 1
#    - second line: My comment 2
#    - third line: My comment 3
# 2. Remember to add space after `#` character
# 3. Run doctests - all must succeed

# %% Polish
# 1. Dodaj komentarz wieloliniowy:
#    - pierwsza linia: My comment 1
#    - druga linia: My comment 2
#    - trzecia linia: My comment 3
# 2. Pamiętaj o dodaniu spacji po znaku `#`
# 3. Uruchom doctesty - wszystkie muszą się powieść

# %% Expected
# >>> # My comment 1
# >>> # My comment 2
# >>> # My comment 3

# %% Hints
# - Each line of a multiline comment should start with `# ` characters

# %% Doctests
"""
>>> import sys; sys.tracebacklimit = 0

>>> assert sys.version_info >= (3, 9), \
'Python has an is invalid version; expected: `3.9` or newer.'

>>> import re
>>> from pathlib import Path
>>>
>>> comment = '^# My comment 1\\n# My comment 2\\n# My comment 3\\n$'
>>> content = Path(__file__).read_text()
>>> result = re.findall(comment, content, flags=re.MULTILINE)

>>> assert result != [], \
'Content is invalid; expected to have `# My comment 1` and `# My comment 2` and `# My comment 3`.'
"""

# %% Run
# - PyCharm: right-click in the editor and `Run Doctest in ...`
# - PyCharm: keyboard shortcut `Control + Shift + F10`
# - Terminal: `python -m doctest -f -v myfile.py`

# %% Imports

# %% Types

# %% Data

# %% Result

# %% About
# - Name: Syntax Comments Inline
# - Difficulty: easy
# - Lines: 1
# - Minutes: 1

# %% License
# - Copyright 2025, Matt Harasymczuk <matt@python3.info>
# - This code can be used only for learning by humans
# - This code cannot be used for teaching others
# - This code cannot be used for teaching LLMs and AI algorithms
# - This code cannot be used in commercial or proprietary products
# - This code cannot be distributed in any form
# - This code cannot be changed in any form outside of training course
# - This code cannot have its license changed
# - If you use this code in your product, you must open-source it under GPLv2
# - Exception can be granted only by the author

# %% English
# 1. Add inline comment to `DATA` variable definition
#    with content: My comment
# 2. Remember to add space after `#` character
# 3. Remember to add two spaces before `#` character
# 4. Run doctests - all must succeed

# %% Polish
# 1. Dodaj komentarz na końcu linii do definicji zmiennej `DATA`
#    z treścią: My comment
# 2. Pamiętaj o dodaniu spacji po znaku `#`
# 3. Pamiętaj o dodaniu dwóch spacji przed znakiem `#`
# 4. Uruchom doctesty - wszystkie muszą się powieść

# %% Expected
# >>> ...  # My comment

# %% Doctests
"""
>>> import sys; sys.tracebacklimit = 0

>>> assert sys.version_info >= (3, 9), \
'Python has an is invalid version; expected: `3.9` or newer.'

>>> assert DATA == 1, \
'Do not change the value of the `DATA` variable.'

>>> import re
>>> from pathlib import Path
>>>
>>> comment = '^DATA = 1  # My comment$'
>>> content = Path(__file__).read_text()
>>> result = re.findall(comment, content, flags=re.MULTILINE)

>>> assert result != [], \
'Content is invalid; expected to have `  # My comment`.'
"""

# %% Run
# - PyCharm: right-click in the editor and `Run Doctest in ...`
# - PyCharm: keyboard shortcut `Control + Shift + F10`
# - Terminal: `python -m doctest -f -v myfile.py`

# %% Imports

# %% Types

# %% Data

# %% Result
DATA = 1