BUG: DataFrame.melt gives unexpected result when column "value" already exists

doc/source/whatsnew/v1.1.0.rst

@@ -816,6 +816,7 @@ Deprecations
 - :meth:`util.testing.assert_almost_equal` now accepts both relative and absolute
   precision through the ``rtol``, and ``atol`` parameters, thus deprecating the
   ``check_less_precise`` parameter. (:issue:`13357`).
+- Issue warning if value column name already exists when using :meth:`DataFrame.melt` (:issue:`34731`)
 
 .. ---------------------------------------------------------------------------
 

pandas/core/reshape/melt.py

@@ -1,5 +1,6 @@
 import re
 from typing import TYPE_CHECKING, List, cast
+import warnings
 
 import numpy as np
 
@@ -40,6 +41,16 @@ def melt(
     else:
         cols = list(frame.columns)
 
+    if value_name in frame.columns:
+        warnings.warn(
+            "This dataframe has a column name that matches the value column "
+            f'name of the resultant melted dataframe (That being "{value_name})". '
+            "In the future this will raise an error, please set the value_name "
+            "parameter of DataFrame.melt to a unique name.",
+            FutureWarning,
+            stacklevel=3,
+        )
+
     if id_vars is not None:
         if not is_list_like(id_vars):
             id_vars = [id_vars]

pandas/tests/reshape/test_melt.py

@@ -1014,3 +1014,12 @@ def test_col_substring_of_stubname(self):
         )
         result = pd.wide_to_long(wide_df, stubnames="PA", i=["node_id", "A"], j="time")
         tm.assert_frame_equal(result, expected)
+
+    def test_warn_of_column_name_value(self):
+        # GH34731
+        # raise a warning if the resultant value column name matches
+        # a name in the dataframe already (default name is "value")
+        df = pd.DataFrame({"col": list("ABC"), "value": range(10, 16, 2)})
+
+        with tm.assert_produces_warning(FutureWarning):
+            dfm = df.melt(id_vars="value")  # noqa F841