From 0237263af95970c3070debb23d84500cb17e5637 Mon Sep 17 00:00:00 2001 From: BethanyG Date: Sun, 8 Feb 2026 10:54:59 -0800 Subject: [PATCH 1/7] Changed pylint comment files to accomodate new pylint code examples. Added general recommendations for exercises that have no comments from analyzer. --- .../python/general/general_recommendations.md | 10 ++++++++++ analyzer-comments/python/pylint/convention.md | 16 +++++++++++----- analyzer-comments/python/pylint/refactor.md | 11 +++++++++-- 3 files changed, 30 insertions(+), 7 deletions(-) create mode 100644 analyzer-comments/python/general/general_recommendations.md diff --git a/analyzer-comments/python/general/general_recommendations.md b/analyzer-comments/python/general/general_recommendations.md new file mode 100644 index 000000000..3f02bc4c2 --- /dev/null +++ b/analyzer-comments/python/general/general_recommendations.md @@ -0,0 +1,10 @@ +1. Get familiar with the conventions outlined in [PEP 8](https://peps.python.org/pep-0008/). While these are not "law", they are the standard used in the Python project itself and are a great baseline in most coding situations. +2. Read and think about the ideas outlined in [PEP 20 (aka "The Zen of Python")](https://peps.python.org/pep-0020/). Like PEP 8, these are not "laws", but they are solid guiding principles for better and clearer Python code. +3. Prefer clear and easy to follow code over comments. But DO comment where needed for clarity. +4. Consider type hints where code is complex or confusing. +5. Try to follow the docstring guidelines laid out in [PEP 257](https://peps.python.org/pep-0257/). Good documentation matters. +6. Write unit tests, but don't obsess over 100% coverage or edge cases. +7. Avoid [magic numbers](https://en.wikipedia.org/wiki/Magic_number_(programming)). +8. Prefer [enumerate](https://docs.python.org/3/library/functions.html#enumerate) over [range(len())](https://docs.python.org/3/library/functions.html#func-range) in loops. +9. Prefer [comprehensions](https://treyhunner.com/2015/12/python-list-comprehensions-now-in-color/) and [generator expressions](https://www.pythonmorsels.com/how-write-generator-expression/) over loops that append to a data structure. But don't [overuse comprehensions](https://treyhunner.com/2019/03/abusing-and-overusing-list-comprehensions-in-python/). +10. Prefer [str.join()](https://docs.python.org/3/library/stdtypes.html#str.join) over other methods of string concatenation. diff --git a/analyzer-comments/python/pylint/convention.md b/analyzer-comments/python/pylint/convention.md index 31393417c..73d81c892 100644 --- a/analyzer-comments/python/pylint/convention.md +++ b/analyzer-comments/python/pylint/convention.md @@ -1,9 +1,15 @@ # pylint convention -**Line %{lineno}** [_%{code}_] : %{message} was reported by Pylint. +**Line %{lineno} [_%{code}_]** was reported by Pylint: -Which means this code doesn't follow general [code style][code style] conventions. -While this type of issue generally doesn't affect the way code _executes_, it can hurt -readability or the performance of automated tools such as documentation generators or test runners. +%{message}. -[code style]: https://www.python.org/dev/peps/pep-0008/ \ No newline at end of file +This code doesn't follow general [Python code style][code style] conventions. +While this type of issue generally doesn't affect the way code _executes_, it can hurt readability or the performance of automated tools such as documentation generators or test runners. + +%Q{Instead of:\n\n```python\n\n#{bad_code}\n```\n} +%Q{Try:\n\n```python\n\n#{good_code}\n```\n\n} +%Q{Additional information:\n #{related_info}\n} +%{details} + +[code style]: https://www.python.org/dev/peps/pep-0008/ diff --git a/analyzer-comments/python/pylint/refactor.md b/analyzer-comments/python/pylint/refactor.md index 422e013ed..706b4e963 100644 --- a/analyzer-comments/python/pylint/refactor.md +++ b/analyzer-comments/python/pylint/refactor.md @@ -1,11 +1,18 @@ # pylint refactor -**Line %{lineno}** [_%{code}_] : %{message} was reported by Pylint. +**Line %{lineno} [_%{code}_]** was reported by Pylint: + +%{message}. This code is emitting a [code smell][code smell], and may be in need of a re-write or refactor. - This doesn't mean the code is incorrect or buggy in a _technical sense_ -- only that it + This doesn't mean the code is incorrect or buggy in a _technical sense_, only that it appears to have one or more patterns that could lead to _future_ bugs or maintenance issues. Consider taking a closer look at it. +%Q{Instead of:\n\n```python\n\n#{bad_code}\n```\n} +%Q{Try:\n\n```python\n\n#{good_code}\n```\n\n} +%Q{Additional information:\n #{related_info}\n} +%{details} + [code smell]: https://en.wikipedia.org/wiki/Code_smell From 64cd5252b7a2ec04b325cc317a5bf873a1b9591a Mon Sep 17 00:00:00 2001 From: BethanyG Date: Mon, 9 Feb 2026 00:39:34 -0800 Subject: [PATCH 2/7] Update analyzer-comments/python/general/general_recommendations.md Co-authored-by: Isaac Good --- analyzer-comments/python/general/general_recommendations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/analyzer-comments/python/general/general_recommendations.md b/analyzer-comments/python/general/general_recommendations.md index 3f02bc4c2..eee60d5d5 100644 --- a/analyzer-comments/python/general/general_recommendations.md +++ b/analyzer-comments/python/general/general_recommendations.md @@ -5,6 +5,6 @@ 5. Try to follow the docstring guidelines laid out in [PEP 257](https://peps.python.org/pep-0257/). Good documentation matters. 6. Write unit tests, but don't obsess over 100% coverage or edge cases. 7. Avoid [magic numbers](https://en.wikipedia.org/wiki/Magic_number_(programming)). -8. Prefer [enumerate](https://docs.python.org/3/library/functions.html#enumerate) over [range(len())](https://docs.python.org/3/library/functions.html#func-range) in loops. +8. Prefer [`enumerate()`](https://docs.python.org/3/library/functions.html#enumerate) over [range(len())](https://docs.python.org/3/library/functions.html#func-range) in loops that need both an index and element. 9. Prefer [comprehensions](https://treyhunner.com/2015/12/python-list-comprehensions-now-in-color/) and [generator expressions](https://www.pythonmorsels.com/how-write-generator-expression/) over loops that append to a data structure. But don't [overuse comprehensions](https://treyhunner.com/2019/03/abusing-and-overusing-list-comprehensions-in-python/). 10. Prefer [str.join()](https://docs.python.org/3/library/stdtypes.html#str.join) over other methods of string concatenation. From 0f862684d355c4e02affd050b93084ed8ea2cf08 Mon Sep 17 00:00:00 2001 From: BethanyG Date: Mon, 9 Feb 2026 00:40:22 -0800 Subject: [PATCH 3/7] Update analyzer-comments/python/pylint/convention.md Co-authored-by: Isaac Good --- analyzer-comments/python/pylint/convention.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/analyzer-comments/python/pylint/convention.md b/analyzer-comments/python/pylint/convention.md index 73d81c892..21f4b3410 100644 --- a/analyzer-comments/python/pylint/convention.md +++ b/analyzer-comments/python/pylint/convention.md @@ -7,8 +7,8 @@ This code doesn't follow general [Python code style][code style] conventions. While this type of issue generally doesn't affect the way code _executes_, it can hurt readability or the performance of automated tools such as documentation generators or test runners. -%Q{Instead of:\n\n```python\n\n#{bad_code}\n```\n} -%Q{Try:\n\n```python\n\n#{good_code}\n```\n\n} +%Q{Instead of:\n\n```python\n#{bad_code}\n```\n} +%Q{Try:\n\n```python\n#{good_code}\n```\n\n} %Q{Additional information:\n #{related_info}\n} %{details} From 145feb6c86527a359d34204094dd62858dd4f838 Mon Sep 17 00:00:00 2001 From: BethanyG Date: Mon, 9 Feb 2026 00:40:39 -0800 Subject: [PATCH 4/7] Update analyzer-comments/python/pylint/refactor.md Co-authored-by: Isaac Good --- analyzer-comments/python/pylint/refactor.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/analyzer-comments/python/pylint/refactor.md b/analyzer-comments/python/pylint/refactor.md index 706b4e963..75aecbe80 100644 --- a/analyzer-comments/python/pylint/refactor.md +++ b/analyzer-comments/python/pylint/refactor.md @@ -10,8 +10,8 @@ a re-write or refactor. appears to have one or more patterns that could lead to _future_ bugs or maintenance issues. Consider taking a closer look at it. -%Q{Instead of:\n\n```python\n\n#{bad_code}\n```\n} -%Q{Try:\n\n```python\n\n#{good_code}\n```\n\n} +%Q{Instead of:\n\n```python\n#{bad_code}\n```\n} +%Q{Try:\n\n```python\n#{good_code}\n```\n\n} %Q{Additional information:\n #{related_info}\n} %{details} From 33e15f1d8ffcd2a602ca0c6cc8c36025b42dbbfa Mon Sep 17 00:00:00 2001 From: BethanyG Date: Mon, 9 Feb 2026 01:00:17 -0800 Subject: [PATCH 5/7] Code review changes and re-arranging for clarity. --- .../python/general/general_recommendations.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/analyzer-comments/python/general/general_recommendations.md b/analyzer-comments/python/general/general_recommendations.md index eee60d5d5..e50889b17 100644 --- a/analyzer-comments/python/general/general_recommendations.md +++ b/analyzer-comments/python/general/general_recommendations.md @@ -1,10 +1,10 @@ 1. Get familiar with the conventions outlined in [PEP 8](https://peps.python.org/pep-0008/). While these are not "law", they are the standard used in the Python project itself and are a great baseline in most coding situations. 2. Read and think about the ideas outlined in [PEP 20 (aka "The Zen of Python")](https://peps.python.org/pep-0020/). Like PEP 8, these are not "laws", but they are solid guiding principles for better and clearer Python code. 3. Prefer clear and easy to follow code over comments. But DO comment where needed for clarity. -4. Consider type hints where code is complex or confusing. +4. Consider using type hints to clarify your code. Explore the type hint [documentation](https://typing.python.org/en/latest/index.html) and [why you might not want to type hint](https://typing.python.org/en/latest/guides/typing_anti_pitch.html). 5. Try to follow the docstring guidelines laid out in [PEP 257](https://peps.python.org/pep-0257/). Good documentation matters. -6. Write unit tests, but don't obsess over 100% coverage or edge cases. -7. Avoid [magic numbers](https://en.wikipedia.org/wiki/Magic_number_(programming)). -8. Prefer [`enumerate()`](https://docs.python.org/3/library/functions.html#enumerate) over [range(len())](https://docs.python.org/3/library/functions.html#func-range) in loops that need both an index and element. -9. Prefer [comprehensions](https://treyhunner.com/2015/12/python-list-comprehensions-now-in-color/) and [generator expressions](https://www.pythonmorsels.com/how-write-generator-expression/) over loops that append to a data structure. But don't [overuse comprehensions](https://treyhunner.com/2019/03/abusing-and-overusing-list-comprehensions-in-python/). -10. Prefer [str.join()](https://docs.python.org/3/library/stdtypes.html#str.join) over other methods of string concatenation. +6. Avoid [magic numbers](https://en.wikipedia.org/wiki/Magic_number_(programming)). +7. Prefer [`enumerate()`](https://docs.python.org/3/library/functions.html#enumerate) over [`range(len())`](https://docs.python.org/3/library/functions.html#func-range) in loops. +8. Prefer [comprehensions](https://treyhunner.com/2015/12/python-list-comprehensions-now-in-color/) and [generator expressions](https://www.pythonmorsels.com/how-write-generator-expression/) over loops that append to a data structure. But don't [overuse comprehensions](https://treyhunner.com/2019/03/abusing-and-overusing-list-comprehensions-in-python/). +9. When joining more than 3 substrings or concatenating in a loop, prefer [`str.join()`](https://docs.python.org/3/library/stdtypes.html#str.join) over other methods of string concatenation. +10. Consider working locally with [PyTest](https://docs.pytest.org/en/stable/), [PyLint](https://www.pylint.org/) or [Ruff](https://docs.astral.sh/ruff/), and a [static type checker](https://typing.python.org/en/latest/index.html#type-checkers). These are all tools widely used by Python professionals and they can help you write cleaner and less buggy code. From 0cfa94fdc5f71bd6aba24307287b20abcefdb95d Mon Sep 17 00:00:00 2001 From: BethanyG Date: Mon, 9 Feb 2026 11:33:47 -0800 Subject: [PATCH 6/7] Updated other PyLint error message classes for Python 3.13. --- analyzer-comments/python/pylint/error.md | 10 +++++++++- analyzer-comments/python/pylint/fatal.md | 5 ++++- analyzer-comments/python/pylint/informatonal.md | 8 +++++++- analyzer-comments/python/pylint/warning.md | 11 +++++++++-- 4 files changed, 29 insertions(+), 5 deletions(-) diff --git a/analyzer-comments/python/pylint/error.md b/analyzer-comments/python/pylint/error.md index dc33af32d..be095c53b 100644 --- a/analyzer-comments/python/pylint/error.md +++ b/analyzer-comments/python/pylint/error.md @@ -1,5 +1,13 @@ # pylint informational -**Line %{lineno}** [_%{code}_] : %{message} was reported by Pylint. +**Line %{lineno} [_%{code}_]** was reported by Pylint: + +%{message}. This code has an error or problem that should be addressed. + +%Q{Instead of:\n\n```python\n#{bad_code}\n```\n} +%Q{Try:\n\n```python\n#{good_code}\n```\n\n} +%Q{Additional information:\n #{related_info}\n} +%{details} + diff --git a/analyzer-comments/python/pylint/fatal.md b/analyzer-comments/python/pylint/fatal.md index 1115b984a..6cf46b72a 100644 --- a/analyzer-comments/python/pylint/fatal.md +++ b/analyzer-comments/python/pylint/fatal.md @@ -1,5 +1,8 @@ # pylint fatal -**Line %{lineno}** [_%{code}_] : %{message} was reported by Pylint. +**Line %{lineno} [_%{code}_]** was reported by Pylint: + +%{message}. + This is a fatal error. Something went wrong, and the code cannot be processed any further. diff --git a/analyzer-comments/python/pylint/informatonal.md b/analyzer-comments/python/pylint/informatonal.md index 05fa5e70e..44913d567 100644 --- a/analyzer-comments/python/pylint/informatonal.md +++ b/analyzer-comments/python/pylint/informatonal.md @@ -1,7 +1,13 @@ # pylint informational +**Line %{lineno} [_%{code}_]** was reported by Pylint: -**Line %{lineno}** [_%{code}_] : %{message} was reported by Pylint. +%{message}. There is `FIXME`/`TODO`/`XXX` style comment or other "informational" pattern or note in the code. These tags are often used to annotate places where code is stubbed out but needs work - or to highlight potential design flaws or bugs that need to be addressed in the future. + +%Q{Instead of:\n\n```python\n#{bad_code}\n```\n} +%Q{Try:\n\n```python\n#{good_code}\n```\n\n} +%Q{Additional information:\n #{related_info}\n} +%{details} diff --git a/analyzer-comments/python/pylint/warning.md b/analyzer-comments/python/pylint/warning.md index 6108e9c7d..040660916 100644 --- a/analyzer-comments/python/pylint/warning.md +++ b/analyzer-comments/python/pylint/warning.md @@ -1,8 +1,15 @@ # pylint warning -**Line %{lineno}** [_%{code}_] : %{message} was reported by Pylint. +**Line %{lineno} [_%{code}_]** was reported by Pylint: + +%{message}. There is an issue in the code that could lead to a bug or error in the program. While this error might not be _severe_, it could lead to more severe issues in the future. -It is recommend the problem be addressed before proceeding further. +It is recommended the problem be addressed before proceeding further. + +%Q{Instead of:\n\n```python\n#{bad_code}\n```\n} +%Q{Try:\n\n```python\n#{good_code}\n```\n\n} +%Q{Additional information:\n #{related_info}\n} +%{details} From 05bffe7e077774744dcb4d196748ea121bff7777 Mon Sep 17 00:00:00 2001 From: BethanyG Date: Mon, 9 Feb 2026 12:45:57 -0800 Subject: [PATCH 7/7] More suggestions from code review and changed inline links to reflinks. --- .../python/general/general_recommendations.md | 40 ++++++++++++++----- 1 file changed, 31 insertions(+), 9 deletions(-) diff --git a/analyzer-comments/python/general/general_recommendations.md b/analyzer-comments/python/general/general_recommendations.md index e50889b17..7536af0e7 100644 --- a/analyzer-comments/python/general/general_recommendations.md +++ b/analyzer-comments/python/general/general_recommendations.md @@ -1,10 +1,32 @@ -1. Get familiar with the conventions outlined in [PEP 8](https://peps.python.org/pep-0008/). While these are not "law", they are the standard used in the Python project itself and are a great baseline in most coding situations. -2. Read and think about the ideas outlined in [PEP 20 (aka "The Zen of Python")](https://peps.python.org/pep-0020/). Like PEP 8, these are not "laws", but they are solid guiding principles for better and clearer Python code. +1. Get familiar with the conventions outlined in [PEP 8][pep-8]. + While these are not "law", they are the standard used in the Python project itself and are a great baseline in most coding situations. +2. Read and think about the ideas outlined in [PEP 20 (aka "The Zen of Python")][pep-20]. + Like PEP 8, these are not "laws", but they are solid guiding principles for better and clearer Python code. 3. Prefer clear and easy to follow code over comments. But DO comment where needed for clarity. -4. Consider using type hints to clarify your code. Explore the type hint [documentation](https://typing.python.org/en/latest/index.html) and [why you might not want to type hint](https://typing.python.org/en/latest/guides/typing_anti_pitch.html). -5. Try to follow the docstring guidelines laid out in [PEP 257](https://peps.python.org/pep-0257/). Good documentation matters. -6. Avoid [magic numbers](https://en.wikipedia.org/wiki/Magic_number_(programming)). -7. Prefer [`enumerate()`](https://docs.python.org/3/library/functions.html#enumerate) over [`range(len())`](https://docs.python.org/3/library/functions.html#func-range) in loops. -8. Prefer [comprehensions](https://treyhunner.com/2015/12/python-list-comprehensions-now-in-color/) and [generator expressions](https://www.pythonmorsels.com/how-write-generator-expression/) over loops that append to a data structure. But don't [overuse comprehensions](https://treyhunner.com/2019/03/abusing-and-overusing-list-comprehensions-in-python/). -9. When joining more than 3 substrings or concatenating in a loop, prefer [`str.join()`](https://docs.python.org/3/library/stdtypes.html#str.join) over other methods of string concatenation. -10. Consider working locally with [PyTest](https://docs.pytest.org/en/stable/), [PyLint](https://www.pylint.org/) or [Ruff](https://docs.astral.sh/ruff/), and a [static type checker](https://typing.python.org/en/latest/index.html#type-checkers). These are all tools widely used by Python professionals and they can help you write cleaner and less buggy code. +4. Consider using type hints to clarify your code. + Explore the type hint [documentation][type-hint-docs] and [why you might not want to type hint][type-hint-nos]. +5. Try to follow the docstring guidelines laid out in [PEP 257][pep-257]. + Good documentation matters. +6. Avoid [magic numbers][magic-numbers]. +7. Prefer [`enumerate()`][enumerate-docs] over [`range(len())`][range-docs] in loops that need both an index and element. +8. Prefer [comprehensions][comprehensions] and [generator expressions][generators] over loops that append to a data structure. + But don't [overuse comprehensions][comprehension-overuse]. +9. When joining more than few substrings or concatenating in a loop, prefer [`str.join()`][join] over other methods of string concatenation. +10. Get familiar with Python's rich set of [built-in functions][built-in-functions] and the [Standard Library][standard-lib]. + Go [here][standard-lib-overview] for a brief tour and some interesting highlights. + +[built-in-functions]: https://docs.python.org/3/library/functions.html +[comprehension-overuse]: https://treyhunner.com/2019/03/abusing-and-overusing-list-comprehensions-in-python/ +[comprehensions]: https://treyhunner.com/2015/12/python-list-comprehensions-now-in-color/ +[enumerate-docs]: https://docs.python.org/3/library/functions.html#enumerate +[generators]: https://www.pythonmorsels.com/how-write-generator-expression/ +[join]: https://docs.python.org/3/library/stdtypes.html#str.join +[magic-numbers]: https://en.wikipedia.org/wiki/Magic_number_(programming) +[pep-20]: https://peps.python.org/pep-0020/ +[pep-257]: https://peps.python.org/pep-0257/ +[pep-8]: https://peps.python.org/pep-0008/ +[range-docs]: https://docs.python.org/3/library/functions.html#func-range +[standard-lib-overview]: https://docs.python.org/3/tutorial/stdlib.html +[standard-lib]: https://docs.python.org/3/library/index.html +[type-hint-docs]: https://typing.python.org/en/latest/index.html +[type-hint-nos]: https://typing.python.org/en/latest/guides/typing_anti_pitch.html