{"id":"code-col-numpy-docstring-moving-average","audience":"college","category":"coding","track":"coding","technique":"grounding","title":"Write a NumPy-style docstring that matches what the code does","free":false,"task":"Your data-science club's library needs a docstring for moving_average before the release. Use NumPy style with exactly three sections in this order: Parameters, Returns, Raises (no Examples or Notes). It must describe what the code really does, not the old comment. Return only the docstring (no def line or body) in exactly 1 code block of at most 24 lines, with under 15 words outside it.","materialLabel":"The function (attached to your prompt automatically)","material":"# clubstats/smoothing.py  (Python 3.11, Data Science Club shared library)\n\ndef moving_average(values, window=3):\n    # returns a list the same length as values, padded with None\n    if window < 1 or window > len(values):\n        raise ValueError(\"window must be between 1 and len(values)\")\n    out = []\n    running = sum(values[:window])\n    out.append(running / window)\n    for i in range(window, len(values)):\n        running += values[i] - values[i - window]\n        out.append(running / window)\n    return out\n\n\n# History:\n#  v0.2 (Mar): padded with None so plots lined up  <- removed in v0.3\n#  v0.3 (Sep): Anika removed the padding, plots now use x offsets\n#\n# Quick check I ran in the REPL:\n#   >>> moving_average([2, 4, 6, 8], window=2)\n#   [3.0, 5.0, 7.0]\n#   >>> moving_average([1, 2], window=5)\n#   ValueError: window must be between 1 and len(values)\n#\n# Club style guide: NumPy docstrings, imperative first line.","rules":[{"type":"codeBlocks","count":1},{"type":"maxCodeLines","max":24},{"type":"maxProseWords","max":15}],"mistakes":[{"title":"Copying the stale comment","why":"The comment still says the output is padded to the same length, and the AI repeats it.","fix":"Add: \"Describe what the code does now, not the comment: the result has len(values) - window + 1 items.\"","checks":["r1"]},{"title":"Wrong style or extra sections","why":"The AI often writes Google style or adds an Examples section.","fix":"Say: \"NumPy style, exactly Parameters, Returns, Raises, in that order. No Examples.\"","checks":["r0"]},{"title":"Forgetting the error","why":"The AI may skip Raises or get the condition wrong.","fix":"Add: \"Raises ValueError if window < 1 or window > len(values).\"","checks":["r2"]},{"title":"The whole function back","why":"The AI pastes the full function with the docstring inside and a note.","fix":"Add: \"Return only the docstring in one code block, no def line.\"","checks":["codeBlocks","maxCodeLines","maxProseWords"]}],"promptHints":[{"label":"Names the style","patterns":["numpy"]},{"label":"Lists the sections","patterns":["parameters","returns","raises"]},{"label":"Says to trust the code","patterns":["not the comment","what the code (does|actually)","shorter","len\\(values\\) - window"]},{"label":"Rules out examples","patterns":["no examples","no notes","exactly three"]},{"label":"Asks for only the docstring","patterns":["only the docstring","no def","just the docstring"]}],"hint":"A docstring that repeats an outdated comment is worse than none. Tell the AI the style, the sections, and to describe what the code does today.","rubricLabels":["Has exactly three NumPy-style sections in the order Parameters, Returns, Raises, each with a dashed underline, and no Examples, Notes or other sections","The Returns section says the list has len(values) - window + 1 floats (shorter than values, no None padding), not the same length as values","The Raises section names ValueError when window is less than 1 or greater than len(values), and the code block holds only the docstring (no def line or function body)"]}