Providing perspective in code

General comments in Python are started using a single hash character #.

# Single line comment precedes a code line
a = 3.14

# A multiline comment is just
# multiple single line comments

b = "some text" # an inline comment

General inline comments are not recommended as they can be easily overlooked, or cause line length issues. However structured inline comments are necessary.

Structured comments are used to contain syntactic information for tools such as flake8 & mypy .

import tempfile  # noqa: F401
import no_annotation_library  # type: ignore

# Note the format here when you want `noqa` to apply to all the imported objects.
from pathlib import (  # noqa: F401
	WindowsPath,
	PosixPath,
)

In the above example, the noqa instruction signals to flake8. The F401 code means for flake8 to ignore that the temp file import is unused in this module, otherwise it will warn & fail out of a flake8 run. If your CI system checks for any flake8 errors (and it should be) then an unused import will cause it to fail and we want to do our best before a push to ensure that the CI run will not fail on our submission.

The type instruction signals to mypy. The ignore instruction means for mypy to not require type annotations from this import. Not a great thing to have to do, but sometimes it’s necessary. Again, your CI should be checking for mypy compliance, and will fail the run on these types of errors if not taken care of by satisfying the type annotations from that library, or telling mypy to ignore the non compliance of that library.

Python documentation:

https://docs.python.org/3/reference/lexical_analysis.html#comments