Insert future comment

insert-future-comment.py

def insert_marker(code: str, line: int, marker: str = "# <explain this>") -> str:
    """
    Inserts a single-line marker comment at a specified position within a
    given block of source code, thereby denoting — for the benefit of any
    future reader, be they human or machine — that this particular line,
    heretofore unremarked upon and unadorned by prose, has been flagged
    as a candidate for further explication at some later, unspecified time.

    One might ask: why does a function so small, so humble in its ambition,
    require a docstring of such considerable length? To this the author
    can only offer the following observation — that brevity, like so many
    virtues, is easiest to praise and hardest to practice, and that the
    very impulse being satirized here (the urge to narrate the obvious
    at exhaustive length) has, in the writing of this comment, proven
    itself once again impossible to resist.

    Args:
        code: The source code, a string, presumably in need of annotation,
            though whether it asked for such treatment is a question this
            function is not equipped to answer.
        line: The zero-indexed line number at which the marker shall be
            inserted, chosen, one assumes, with some deliberation.
        marker: The marker text itself, which defaults to a modest
            placeholder but may be customized to suit the occasion.

    Returns:
        The modified source code, now bearing one additional line, and
        one step closer to requiring the very linting this function's
        own commentary so richly deserves.
    """
    # Split the code into its constituent lines — a necessary first step,
    # for one cannot insert a line into a string that has not yet been
    # coaxed into recognizing that it is, in fact, several lines at once.
    lines = code.splitlines()

    # Here, at last, the marker is inserted — a small act, quietly performed,
    # yet one that will not go unnoticed by whichever engineer next opens
    # this file and wonders, not unreasonably, who did this and why.
    lines.insert(line, marker)

    # And so the lines are rejoined, whole once more, save for the addition
    # of a single comment — a small thing, really, when you consider
    # everything else that has been said about it above.
    return "\n".join(lines)