Docs: Missing Docstrings in ensure_sorted.py#622
Closed
maptoan wants to merge 1 commit intooffa:masterfrom
Closed
Conversation
The `Category` class and its methods (`add_app`, `is_sorted`, `where_unsorted`, `how_to_sort`), as well as the `main` function, lack docstrings. This makes it harder for future maintainers to understand the purpose, arguments, and return values of these components without reading the entire implementation. Given this script is part of the CI pipeline, its clarity is important for project health and maintainability. Affected files: ensure_sorted.py Signed-off-by: toanmap <174589430+maptoan@users.noreply.github.com>
offa
reviewed
Mar 30, 2026
| Args: | ||
| app_str (str): The markdown string representing an app (e.g., "* [**App Name**](link)"). | ||
| """ | ||
| matches = re.findall("(?<=\[\\*\\*).*(?=\\*\\*\])", app_str) |
maptoan
deleted the
contribai/docs/missing-docstrings-in-ensure-sorted-py
branch
Owner
|
Thank you for the contribution. However, I'm not entirely convinced that the docstrings add real value. In most cases, they simply elaborate on the function name or are even longer than the entire implementation. Additionally, they risk becoming outdated when the code changes. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
📝 Documentation
Problem
The
Categoryclass and its methods (add_app,is_sorted,where_unsorted,how_to_sort), as well as themainfunction, lack docstrings. This makes it harder for future maintainers to understand the purpose, arguments, and return values of these components without reading the entire implementation. Given this script is part of the CI pipeline, its clarity is important for project health and maintainability.Severity:
mediumFile:
ensure_sorted.pySolution
Add concise docstrings to the
Categoryclass, its methods, and themainfunction to explain their roles and functionality.Example for
Categoryclass:Changes
ensure_sorted.py(modified)Testing
🤖 About this PR
This pull request was generated by ContribAI, an AI agent
that helps improve open source projects. The change was:
If you have questions or feedback about this PR, please comment below.
We appreciate your time reviewing this contribution!
Closes #621