During a peer review of a production-bound Python ETL script that will feed a real-time ML inference service, you notice the following:
Every function begins with a block comment such as # reads csv and cleans data, but there are no docstrings.
Inline comments appear on almost every line, including obvious ones (e.g., i += 1 # increment counter).
An earlier version of a feature-engineering function is still present but fully commented-out.
The team generates API documentation with Sphinx and already stores code history in Git.
Which revision would best bring the script in line with appropriate code commenting practices for process documentation in the data-science life cycle?
Convert each inline comment into a runtime logging statement so the execution trace doubles as documentation and remove docstrings to avoid redundancy.
Leave the detailed inline comments in place, add TODO tags to mark functions needing refactoring, and keep the commented-out legacy code so future developers can study earlier implementations.
Replace the block comments with module-, class-, and function-level docstrings that clearly state purpose, parameters, returns, and side effects; keep brief inline comments only where the intent is not obvious; and delete the commented-out legacy code because Git already preserves it.
Strip all comments and docstrings before committing the file to production to reduce file size, and move the descriptive text to an external wiki that developers can consult when necessary.
Well-written process documentation should live as close to the code as possible so that tools such as Sphinx can extract it automatically and future engineers see authoritative information at the point of use. Module-, class-, and function-level docstrings that describe purpose, parameters, return values, exceptions, and side effects satisfy that goal and adhere to conventions such as PEP 257, Google, or NumPy style. Keeping only a few explanatory inline comments for non-obvious logic avoids pointless noise, while deleting commented-out code relies on the version-control system to preserve history. The other choices either retain poor practices (excessive inline comments, TODO clutter, commented-out code), discard in-code documentation entirely (separate wiki), or misuse runtime logging as documentation-all of which hinder maintainability and violate accepted commenting guidelines.
Ask Bash
Bash is our AI bot, trained to help you pass your exam. AI Generated Content may display inaccurate information, always double-check anything important.
What is a docstring in Python and why is it important?
Open an interactive chat with Bash
Why should commented-out legacy code be removed if Git is used?
Open an interactive chat with Bash
What are appropriate uses for inline comments in Python?