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

"""
* 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ść

Hints:
    * Use `#` character to start a comment
    * Remember to add space after `#` character
    * Each line of a comment should start with `# ` characters

Tests:
    >>> import sys; sys.tracebacklimit = 0

    >>> result = open(__file__).read()
    >>> comment = '#' + ' ' + 'This is my first Python script'

    >>> assert comment in result, \
    'Please write proper line comment'
"""

"""
* 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ść

Hints:
    * Use `#` character to start a comment
    * Remember to add space after `#` character
    * Each line of a multiline comment should start with `# ` characters

Tests:
    >>> import sys; sys.tracebacklimit = 0

    >>> result = open(__file__).read()
    >>> comment = '\\n'.join([
    ...     '#' + ' ' + 'This is a first line of a multiline comment',
    ...     '#' + ' ' + 'This is a second line of a multiline comment',
    ...     '#' + ' ' + 'This is a third line of a multiline comment',
    ... ])

    >>> assert comment in result, \
    'Please write proper multiline comment'
"""

"""
* Assignment: Syntax Comments Inline
* Type: class assignment
* Complexity: easy
* Lines of code: 1 line
* Time: 2 min

English:
    1. Add inline comment to `name` variable definition
       with content: This is inline comment
    2. Run doctests - all must succeed

Polish:
    1. Dodaj komentarz na końcu linii do definicji zmiennej `name`
       treść: This is inline comment
    2. Uruchom doctesty - wszystkie muszą się powieść

Hints:
    * Use `#` character to start a comment
    * Remember to add space after `#` character
    * Inline comment should be separated with two spaces from the code

Tests:
    >>> import sys; sys.tracebacklimit = 0

    >>> result = open(__file__).read()
    >>> comment = '  ' + '#' + ' ' + 'This is inline comment'

    >>> assert type(name) is str, \
    'Variable `name` has invalid type, should be str'

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

    >>> assert comment in result, \
    'Please write proper inline comment'

"""

name = 'Mark Watney'