deprecate check-docstring-first without replacement

asottile · asottile · commit d2cf95b9cf90 · 2025-11-22T15:21:07.000-05:00
this hook has unfixable false positives and is not that useful

perhaps someone can write a flake8 plugin to replace the functionality
diff --git a/.pre-commit-hooks.yaml b/.pre-commit-hooks.yaml
@@ -29,7 +29,7 @@
     entry: check-case-conflict
     language: python
 -   id: check-docstring-first
-    name: check docstring is first
+    name: check docstring is first (deprecated)
     description: checks a common error of defining a docstring after code.
     entry: check-docstring-first
     language: python
diff --git a/README.md b/README.md
@@ -45,9 +45,6 @@ Require literal syntax when initializing empty or zero Python builtin types.
 #### `check-case-conflict`
 Check for files with names that would conflict on a case-insensitive filesystem like MacOS HFS+ or Windows FAT.
 
-#### `check-docstring-first`
-Checks for a common error of placing code before the docstring.
-
 #### `check-executables-have-shebangs`
 Checks that non-binary executables have a proper shebang.
 
@@ -207,6 +204,8 @@ Trims trailing whitespace.
 
 - `check-byte-order-marker`: instead use fix-byte-order-marker
 - `fix-encoding-pragma`: instead use [`pyupgrade`](https://github.com/asottile/pyupgrade)
+- `check-docstring-first`: fundamentally flawed, deprecated without replacement.
+
 
 ### As a standalone package
 
