diff --git a/crates/ruff/src/rules/flake8_fixme/rules/todos.rs b/crates/ruff/src/rules/flake8_fixme/rules/todos.rs index d43d20b623..aa733b344f 100644 --- a/crates/ruff/src/rules/flake8_fixme/rules/todos.rs +++ b/crates/ruff/src/rules/flake8_fixme/rules/todos.rs @@ -3,39 +3,114 @@ use ruff_macros::{derive_message_formats, violation}; use crate::directives::{TodoComment, TodoDirectiveKind}; +/// ## What it does +/// Checks for "TODO" comments. +/// +/// ## Why is this bad? +/// "TODO" comments are used to describe an issue that should be resolved +/// (usually, a missing feature, optimization, or refactoring opportunity). +/// +/// Consider resolving the issue before deploying the code. +/// +/// Note that if you use "TODO" comments as a form of documentation (e.g., +/// to [provide context for future work](https://gist.github.com/dmnd/ed5d8ef8de2e4cfea174bd5dafcda382)), +/// this rule may not be appropriate for your project. +/// +/// ## Example +/// ```python +/// def greet(name): +/// return f"Hello, {name}!" # TODO: Add support for custom greetings. +/// ``` #[violation] pub struct LineContainsTodo; impl Violation for LineContainsTodo { #[derive_message_formats] fn message(&self) -> String { - format!("Line contains TODO") + format!("Line contains TODO, consider resolving the issue") } } +/// ## What it does +/// Checks for "FIXME" comments. +/// +/// ## Why is this bad? +/// "FIXME" comments are used to describe an issue that should be resolved +/// (usually, a bug or unexpected behavior). +/// +/// Consider resolving the issue before deploying the code. +/// +/// Note that if you use "FIXME" comments as a form of documentation, this +/// rule may not be appropriate for your project. +/// +/// ## Example +/// ```python +/// def speed(distance, time): +/// return distance / time # FIXME: Raises ZeroDivisionError for time = 0. +/// ``` #[violation] pub struct LineContainsFixme; impl Violation for LineContainsFixme { #[derive_message_formats] fn message(&self) -> String { - format!("Line contains FIXME") + format!("Line contains FIXME, consider resolving the issue") } } +/// ## What it does +/// Checks for "XXX" comments. +/// +/// ## Why is this bad? +/// "XXX" comments are used to describe an issue that should be resolved. +/// +/// Consider resolving the issue before deploying the code, or, at minimum, +/// using a more descriptive comment tag (e.g, "TODO"). +/// +/// ## Example +/// ```python +/// def speed(distance, time): +/// return distance / time # XXX: Raises ZeroDivisionError for time = 0. +/// ``` #[violation] pub struct LineContainsXxx; impl Violation for LineContainsXxx { #[derive_message_formats] fn message(&self) -> String { - format!("Line contains XXX") + format!("Line contains XXX, consider resolving the issue") } } +/// ## What it does +/// Checks for "HACK" comments. +/// +/// ## Why is this bad? +/// "HACK" comments are used to describe an issue that should be resolved +/// (usually, a suboptimal solution or temporary workaround). +/// +/// Consider resolving the issue before deploying the code. +/// +/// Note that if you use "TODO" comments as a form of documentation, this +/// rule may not be appropriate for your project. +/// +/// ## Example +/// ```python +/// import os +/// +/// +/// def running_windows(): # HACK: Use platform module instead. +/// try: +/// os.mkdir("C:\\Windows\\System32\\") +/// except FileExistsError: +/// return True +/// else: +/// os.rmdir("C:\\Windows\\System32\\") +/// return False +/// ``` #[violation] pub struct LineContainsHack; impl Violation for LineContainsHack { #[derive_message_formats] fn message(&self) -> String { - format!("Line contains HACK") + format!("Line contains HACK, consider resolving the issue") } } diff --git a/crates/ruff/src/rules/flake8_fixme/snapshots/ruff__rules__flake8_fixme__tests__line-contains-fixme_T00.py.snap b/crates/ruff/src/rules/flake8_fixme/snapshots/ruff__rules__flake8_fixme__tests__line-contains-fixme_T00.py.snap index 3b5655e30a..fd3b5650b6 100644 --- a/crates/ruff/src/rules/flake8_fixme/snapshots/ruff__rules__flake8_fixme__tests__line-contains-fixme_T00.py.snap +++ b/crates/ruff/src/rules/flake8_fixme/snapshots/ruff__rules__flake8_fixme__tests__line-contains-fixme_T00.py.snap @@ -1,7 +1,7 @@ --- source: crates/ruff/src/rules/flake8_fixme/mod.rs --- -T00.py:7:3: FIX001 Line contains FIXME +T00.py:7:3: FIX001 Line contains FIXME, consider resolving the issue | 5 | # HACK: hack 6 | # hack: hack @@ -10,7 +10,7 @@ T00.py:7:3: FIX001 Line contains FIXME 8 | # fixme: fixme | -T00.py:8:3: FIX001 Line contains FIXME +T00.py:8:3: FIX001 Line contains FIXME, consider resolving the issue | 6 | # hack: hack 7 | # FIXME: fixme diff --git a/crates/ruff/src/rules/flake8_fixme/snapshots/ruff__rules__flake8_fixme__tests__line-contains-hack_T00.py.snap b/crates/ruff/src/rules/flake8_fixme/snapshots/ruff__rules__flake8_fixme__tests__line-contains-hack_T00.py.snap index 581a3b4f40..af6e776411 100644 --- a/crates/ruff/src/rules/flake8_fixme/snapshots/ruff__rules__flake8_fixme__tests__line-contains-hack_T00.py.snap +++ b/crates/ruff/src/rules/flake8_fixme/snapshots/ruff__rules__flake8_fixme__tests__line-contains-hack_T00.py.snap @@ -1,7 +1,7 @@ --- source: crates/ruff/src/rules/flake8_fixme/mod.rs --- -T00.py:5:3: FIX004 Line contains HACK +T00.py:5:3: FIX004 Line contains HACK, consider resolving the issue | 3 | # XXX: xxx 4 | # xxx: xxx @@ -11,7 +11,7 @@ T00.py:5:3: FIX004 Line contains HACK 7 | # FIXME: fixme | -T00.py:6:3: FIX004 Line contains HACK +T00.py:6:3: FIX004 Line contains HACK, consider resolving the issue | 4 | # xxx: xxx 5 | # HACK: hack diff --git a/crates/ruff/src/rules/flake8_fixme/snapshots/ruff__rules__flake8_fixme__tests__line-contains-todo_T00.py.snap b/crates/ruff/src/rules/flake8_fixme/snapshots/ruff__rules__flake8_fixme__tests__line-contains-todo_T00.py.snap index 8356bff928..291305b5e5 100644 --- a/crates/ruff/src/rules/flake8_fixme/snapshots/ruff__rules__flake8_fixme__tests__line-contains-todo_T00.py.snap +++ b/crates/ruff/src/rules/flake8_fixme/snapshots/ruff__rules__flake8_fixme__tests__line-contains-todo_T00.py.snap @@ -1,7 +1,7 @@ --- source: crates/ruff/src/rules/flake8_fixme/mod.rs --- -T00.py:1:3: FIX002 Line contains TODO +T00.py:1:3: FIX002 Line contains TODO, consider resolving the issue | 1 | # TODO: todo | ^^^^ FIX002 @@ -9,7 +9,7 @@ T00.py:1:3: FIX002 Line contains TODO 3 | # XXX: xxx | -T00.py:2:3: FIX002 Line contains TODO +T00.py:2:3: FIX002 Line contains TODO, consider resolving the issue | 1 | # TODO: todo 2 | # todo: todo diff --git a/crates/ruff/src/rules/flake8_fixme/snapshots/ruff__rules__flake8_fixme__tests__line-contains-xxx_T00.py.snap b/crates/ruff/src/rules/flake8_fixme/snapshots/ruff__rules__flake8_fixme__tests__line-contains-xxx_T00.py.snap index 53b7088b70..e1123d8b76 100644 --- a/crates/ruff/src/rules/flake8_fixme/snapshots/ruff__rules__flake8_fixme__tests__line-contains-xxx_T00.py.snap +++ b/crates/ruff/src/rules/flake8_fixme/snapshots/ruff__rules__flake8_fixme__tests__line-contains-xxx_T00.py.snap @@ -1,7 +1,7 @@ --- source: crates/ruff/src/rules/flake8_fixme/mod.rs --- -T00.py:3:3: FIX003 Line contains XXX +T00.py:3:3: FIX003 Line contains XXX, consider resolving the issue | 1 | # TODO: todo 2 | # todo: todo @@ -11,7 +11,7 @@ T00.py:3:3: FIX003 Line contains XXX 5 | # HACK: hack | -T00.py:4:3: FIX003 Line contains XXX +T00.py:4:3: FIX003 Line contains XXX, consider resolving the issue | 2 | # todo: todo 3 | # XXX: xxx