2.4. Syntax Comments

  • Line Comments

  • Multiline Comments

  • Inline Comments

2.4.1. Line Comments

  • PEP 8 -- Style Guide for Python Code: for line comments: Hash (#), space and then comment

>>> # Mark thinks he is...
>>> print('Mark Watney: Space Pirate')
Mark Watney: Space Pirate

2.4.2. Multiline Comments

  • There are no multiline comments in Python

  • You can create many one line comments

>>> # Mark thinks...
>>> # he is...
>>> print('Mark Watney: Space Pirate')
Mark Watney: Space Pirate

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.

>>> 
... """
... This is first line of a multiline comment
... This is second line of a multiline comment
... """

2.4.3. Inline Comments

  • PEP 8 -- Style Guide for Python Code: for inline comments: code, two spaces, hash (#), space and then comment

>>> print('Mark Watney: Space Pirate')  # This is who Mark Watney is
Mark Watney: Space Pirate

2.4.4. Docstring and Doctests

  • Docstring is a first multiline comment in: File/Module, Class, Method/Function

  • Used for doctest

  • More information in Function Doctest

  • PEP 257 -- Docstring Conventions: For multiline str always use three double quote (""") characters

>>> 
... """
... This is my first Python script
...
... >>> result
... 12
... """
>>>
>>> result = 10 + 2

2.4.5. Good Practices

  • If you need comments, you failed with writing clean code

  • Instead of comments write more readable code

  • Never commit commented out code

  • Use Version Control System instead - e.g.: git blame

  • IDE has Local history (modifications) and you can compare file

2.4.6. Assignments

Code 2.7. assignments/syntax_comments_a.py
"""
* Assignment: Syntax Comments Line
* Type: class assignment
* Complexity: easy
* Lines of code: 1 line
* Time: 2 min

English:
    1. Add line comment: This is my first Python script
    2. Run doctests - all must succeed

Polish:
    1. Dodaj komentarz liniowy: This is my first Python script
    2. Uruchom doctesty - wszystkie muszą się powieść

Tests:
    >>> import sys; sys.tracebacklimit = 0
    >>> result = open(__file__).read()

    >>> assert '# This is my first Python script' in result, \
    'Please write proper line comment'
"""
Code 2.8. assignments/syntax_comments_b.py
"""
* Assignment: Syntax Comments Multiline
* Type: class assignment
* Complexity: easy
* Lines of code: 3 lines
* Time: 2 min

English:
    1. Add multiline comment
       a. first line: This is a first line of a multiline comment
       b. second line: This is a second line of a multiline comment
       b. third line: This is a third line of a multiline comment
    2. Run doctests - all must succeed

Polish:
    1. Dodaj komentarz wieloliniowy
       a. pierwsza linia: This is a first line of a multiline comment
       b. druga linia: This is a second line of a multiline comment
       c. trzecia linia: This is a third line of a multiline comment
    2. Uruchom doctesty - wszystkie muszą się powieść

Tests:
    >>> import sys; sys.tracebacklimit = 0
    >>> result = open(__file__).read()

    >>> assert '# This is a first line of a multiline comment' in result, \
    'Please write proper multiline comment'
    >>> assert '# This is a second line of a multiline comment' in result, \
    'Please write proper multiline comment'
    >>> assert '# This is a third line of a multiline comment' in result, \
    'Please write proper multiline comment'
"""
Code 2.9. assignments/syntax_comments_c.py
"""
* Assignment: Syntax Comments Inline
* Type: class assignment
* Complexity: easy
* Lines of code: 1 line
* Time: 2 min

English:
    1. Add inline comment to `alone_on_mars` variable definition
       with content: Space Pirate
    2. Run doctests - all must succeed

Polish:
    1. Dodaj komentarz na końcu linii do definicji zmiennej `alone_on_mars`
       treść: Space Pirate
    2. Uruchom doctesty - wszystkie muszą się powieść

Tests:
    >>> import sys; sys.tracebacklimit = 0
    >>> result = open(__file__).read()

    >>> assert type(alone_on_mars) is str, \
    'Variable `alone_on_mars` has invalid type, should be str'
    >>> assert "alone_on_mars = 'Mark Watney'  # Space Pirate" in result, \
    'Please write proper inline comment'

    >>> assert alone_on_mars == 'Mark Watney', \
    'Do not change the value of the `alone_on_mars` variable.'
"""

alone_on_mars = 'Mark Watney'