Give a UserWarning when Parameter is overriden by name

CHANGES.rst

@@ -5,6 +5,9 @@ Version 8.2.0
 
 Unreleased
 
+-   Adds a UserWarning when multiple parameters attempt to use the same
+    name. :issue:`2396``
+
 
 Version 8.1.3
 -------------

src/click/decorators.py

@@ -267,6 +267,22 @@ def _param_memo(f: FC, param: Parameter) -> None:
     else:
         if not hasattr(f, "__click_params__"):
             f.__click_params__ = []  # type: ignore
+        else:
+            for opt in param.opts:
+                for preexisting_param in f.__click_params__:  # type: ignore
+                    if opt in preexisting_param.opts:
+
+                        from warnings import warn
+
+                        warn(
+                            (
+                                "Duplicate option added to command."
+                                " The following option appears more than once:\n"
+                                f"{opt} (used for {param.human_readable_name}"
+                                f" and {preexisting_param.human_readable_name})"
+                            ),
+                            stacklevel=3,
+                        )
 
         f.__click_params__.append(param)  # type: ignore
 

tests/test_options.py

@@ -922,3 +922,13 @@ def test_invalid_flag_combinations(runner, kwargs, message):
         click.Option(["-a"], **kwargs)
 
     assert message in str(e.value)
+
+
+def test_overridden_option_triggers_warning(runner):
+    with pytest.warns(UserWarning):
+
+        @click.command()
+        @click.option("-a", "--aardvark")
+        @click.option("-a", "--avocado")
+        def cli(aardvark, avocado):
+            pass