Python Comments & Docstrings
Write code that explains itself

A single-line comment: the whole line is ignored.
x = 10  An inline comment: only text after the # is ignored.

print(x)  prints 10

A URL inside a comment doesn't start a second comment:
https://example.com/docs
url = "https://example.com"  a string, not a comment

Idiomatic multi-line comment:
each line is a separate # comment.
Readable, greppable, and unambiguous.

The triple-quoted string below looks like a comment
but is actually an unassigned string literal:
"""This is NOT a comment.

It is a string expression whose result is discarded.
If this is the FIRST statement in a module/class/function,
Python stores it in __doc__ as a docstring instead.
"""

y = 42
print(y)

def add(a: int, b: int) -> int:
    """Return the sum of two integers."""
    return a + b

print(add.__doc__)
print(add(2, 3))

def add_no_doc(a, b):
    This is a comment, not a docstring.
    return a + b

print(add_no_doc.__doc__)

"""geometry.py — small 2D helpers.

This module-level docstring describes the file.
"""

class Circle:
    """A circle with a given radius."""

    def __init__(self, radius: float) -> None:
        """Initialise a circle.

        Args:
            radius: Must be non-negative.
        """
        if radius < 0:
            raise ValueError("radius must be non-negative")
        self.radius = radius

    def area(self) -> float:
        """Return the area of the circle (πr²)."""
        import math
        return math.pi * self.radius ** 2

c = Circle(2)
print(f"area ≈ {c.area():.2f}")

def double(n: int) -> int:
    """Return n multiplied by 2."""
    return n * 2

def clamp(value: float, lo: float, hi: float) -> float:
    """Restrict value to the closed interval [lo, hi].

    If value is below lo, returns lo.
    If value is above hi, returns hi.
    Otherwise returns value unchanged.

    Args:
        value: The number to clamp.
        lo: The lower bound (inclusive).
        hi: The upper bound (inclusive).

    Returns:
        The clamped value.
    """
    return max(lo, min(value, hi))

print(double(7))
print(clamp(15, 0, 10))
print(clamp(-3, 0, 10))
print(clamp(5, 0, 10))

def mean(values: list[float]) -> float:
    """Return the arithmetic mean of the given values.

    Args:
        values: A non-empty sequence of numeric values.

    Returns:
        The arithmetic mean as a float.

    Raises:
        ValueError: If ``values`` is empty.
    """
    if not values:
        raise ValueError("values must not be empty")
    return sum(values) / len(values)

print(mean([2, 4, 6, 8]))

def fetch(url: str, timeout: int = 10) -> bytes:
    """Fetch the given URL and return the response body.

    Args:
        url: A fully-qualified HTTP or HTTPS URL.
        timeout: Seconds to wait before raising.

    Returns:
        The response body as raw bytes.

    Raises:
        TimeoutError: If the request exceeds ``timeout``.
    """
    import urllib.request
    with urllib.request.urlopen(url, timeout=timeout) as r:
        return r.read()

print(len(fetch("https://example.com")))

def correlate(x: list[float], y: list[float]) -> float:
    """Compute the Pearson correlation coefficient.

    Parameters
    ----------
    x : list of float
        First sequence of numeric values. Must have the same length as ``y``.
    y : list of float
        Second sequence of numeric values.

    Returns
    -------
    float
        The Pearson correlation coefficient in [-1.0, 1.0].

    Raises
    ------
    ValueError
        If ``x`` and ``y`` have different lengths.
    """
    if len(x) != len(y):
        raise ValueError("x and y must have equal length")
    n = len(x)
    mx = sum(x) / n
    my = sum(y) / n
    num = sum((a - mx) * (b - my) for a, b in zip(x, y))
    den = (sum((a - mx) ** 2 for a in x) * sum((b - my) ** 2 for b in y)) ** 0.5
    return num / den

print(correlate([1, 2, 3], [2, 4, 6]))

def slugify(text: str) -> str:
    """Convert text to a URL-safe slug.

    Lowercases the input, replaces whitespace runs with single hyphens,
    and strips leading/trailing hyphens.

    :param text: The input string to slugify.
    :type text: str
    :returns: The slugified string.
    :rtype: str
    """
    import re
    s = text.strip().lower()
    s = re.sub(r"\s+", "-", s)
    return s.strip("-")

print(slugify("  Hello, Python World!  "))

def greet(name: str) -> str:
    """Return a friendly greeting.

    Args:
        name: The person to greet.

    Returns:
        A greeting string of the form "Hello, !".
    """
    return f"Hello, {name}!"

print(greet.__doc__)
print("---")
print(greet.__doc__.splitlines()[0])

def add(a: int, b: int) -> int:
    """Return the sum of a and b.

    >>> add(2, 3)
    5
    >>> add(-1, 1)
    0
    >>> add(0, 0)
    0
    """
    return a + b

import doctest
result = doctest.testmod()
print(result)

def divide(a: float, b: float) -> float:
    """Divide a by b.

    >>> divide(10, 3)
    3.3333333333333335
    >>> round(divide(10, 3), 2)
    3.33
    """
    return a / b

def area_of_rectangle(w, h):
    '''Computes the area.'''
    return w * h

def greet(name: str) -> str:
    """Return a friendly greeting."""
    return f"Hello, {name}!"