Catalog / Primitives / change-signature

Change Signature

Adds, removes and reorders the parameters of a method or constructor, and updates every call in the solution to match. Overrides, overridden methods, interface members and their implementations change together, since they must keep the same parameters.

Many composites build on this primitive: Introduce Parameter Object, Preserve Whole Object, Parameterise Method and Constructor Injection all change a signature as one of their steps.

Arguments

parameters is the complete new parameter list, in order. An existing parameter is named; a new one also gives its type, and either the value every existing call passes for it or a default, or both. A parameter of the old signature that is not listed is removed.

"arguments": {
  "parameters": [
    { "name": "b" },
    { "name": "a" },
    { "name": "scale", "type": "int", "value": "1" },
    { "name": "label", "type": "string?", "default": "null" }
  ]
}

Field	Meaning
`name`	an existing parameter's name, or the new parameter's name
`type`	the type of a new parameter; given only for new parameters
`value`	a C# expression each existing call passes for a new parameter
`default`	a default value declared for a new parameter; with no `value`, existing calls leave it out

replacements is optional. For a removed parameter the body still uses, it gives the expression that takes the place of each use, usually one reading the parameter's value from a new parameter:

"arguments": {
  "parameters": [ { "name": "point", "type": "Point", "value": "new Point(3, 4)" } ],
  "replacements": { "x": "point.X", "y": "point.Y" }
}

The target is the method or constructor, by symbol. Targeting an override or an implementation changes the whole family.

Precondition

Every listed name is either an existing parameter or comes with a type.
A new parameter has a value for existing calls, a default, or both.
No removed parameter is read or written in the body of any member of the family, unless replacements gives an expression for it. A replaced parameter is only read, never assigned, and only removed parameters are replaced.
A params array stays last, and no required parameter follows an optional one.
The this parameter of an extension method stays first.
Every member of the family is declared in the solution; a method that implements or overrides a member from a referenced assembly cannot change.
The method is only called, never converted to a delegate: a method group would no longer match its delegate type.
The result compiles.

Transformation

Each declaration in the family gets the new parameter list. New parameters are declared with the given type and default.
Each use of a replaced parameter, in every body of the family, becomes its expression, in parentheses unless it is a name or member access.
Each call's arguments are rearranged into the new order, with the given value for each new parameter and nothing for a removed one. This covers invocations, base calls, object creation, target-typed new, and this() and base() constructor initializers.
Named arguments keep their names. Once a call leaves an optional parameter to its default, every argument after it is named.
The arguments a call passes to a params array in expanded form stay together, in order, at the end.
A call to an extension method in reduced form keeps its receiver.
References in nameof and documentation comments are left alone.

Preserved

Every call passes the same values to the same parameters, so the method sees what it saw before, apart from new parameters, which receive the given value.
Layout: each position in a parameter or argument list keeps its line breaks and indentation, so a list laid out one per line stays that way.
Comments travel with the parameter or argument they belong to, including a line comment after its comma.
Nullable annotations on new and existing parameters.

Limitations

Arguments are evaluated in the new parameter order, so reordering calls whose arguments have side effects that depend on each other changes the order those side effects happen in.
A removed parameter's argument is dropped even if evaluating it had side effects. Remove Unused Parameter refuses in that case.
A replacement is taken on trust: behaviour is preserved only when, at every call, the expression gives the value the call passed for the parameter.
<param> elements in documentation comments are not reordered, added or removed, and cref references with parameter lists are not updated.
Delegates, indexers, operators, attribute constructors and primary constructors are not covered.
A call that passes several values to a params array after an argument it leaves out cannot be named, and is refused.

Error codes

Code	Meaning
`removed-parameter-in-use`	a parameter left out of the new list is used in a body
`replaced-parameter-assigned`	a parameter given a replacement is assigned in a body
`replaced-parameter-kept`	a parameter given a replacement is still in the new list
`unknown-parameter`	a listed name is not a parameter and has no type to add it
`duplicate-parameter`	a new parameter has the name of an existing one
`missing-value`	a new parameter has neither a value for calls nor a default
`optional-before-required`	a required parameter would follow an optional one
`params-not-last`	a params array would not be last
`extension-this-moved`	the `this` parameter of an extension method would move
`method-group-reference`	the method is used as a method group
`external-member`	the method overrides or implements a member outside the solution

Cases

Diffs show each file from before to after. /*[*/ … /*]*/ marks a selection and /*^*/ a caret; the runner removes them before the refactoring runs.

#add-parameter-across-files

Adds a parameter and passes the given value at calls in another file

success

Targetsymbol M:Shop.Order.Total(System.Decimal)

Arguments

`parameters`	`[{"name": "subtotal"}, {"name": "shipping", "type": "decimal", "value": "0m"}]`

Checkout.csmodified

Order.csmodified

1	1		namespace Shop;
2	2
3	3		public class Checkout
4	4		{
5	5		public decimal Pay(Order order)
6	6		{
7		−	return order.Total(100m) + order.Total(20m);
	7	+	return order.Total(100m, 0m) + order.Total(20m, 0m);
8	8		}
9	9		}

1	1		namespace Shop;
2	2
3	3		public class Order
4	4		{
5		−	public decimal Total(decimal subtotal)
	5	+	public decimal Total(decimal subtotal, decimal shipping)
6	6		{
7	7		return subtotal;
8	8		}
9	9		}

1	1		namespace Shop;
2	2
3	3		public class Account
4	4		{
5	5		private readonly string _owner;
6	6
7		−	public Account(string owner)
	7	+	public Account(string owner, decimal limit)
8	8		{
9	9		_owner = owner;
10	10		}
11	11
12		−	public Account() : this("guest")
	12	+	public Account() : this("guest", 0m)
13	13		{
14	14		}
15	15
16	16		public string Owner => _owner;
17	17		}
18	18
19	19		public class Savings : Account
20	20		{
21		−	public Savings(string owner) : base(owner)
	21	+	public Savings(string owner) : base(owner, 0m)
22	22		{
23	23		}
24	24		}

1	1		namespace Shop;
2	2
3	3		public class Bank
4	4		{
5	5		public Account Open(string name)
6	6		{
7		−	Account first = new Account(name);
8		−	Account second = new("joint");
	7	+	Account first = new Account(name, 0m);
	8	+	Account second = new("joint", 0m);
9	9		return first.Owner == name ? first : second;
10	10		}
11	11		}

1		namespace Shop;
2
3		public class Pricing
4		{
5		public decimal Discount(decimal price, int percent)
6		{
7		return price * percent / 100m;
8		}
9		}

1	1		namespace Shop;
2	2
3	3		public static class TextExtensions
4	4		{
5		−	public static string Truncate(this string text, int length)
	5	+	public static string Truncate(this string text, int length, string ellipsis)
6	6		{
7	7		return text.Length <= length ? text : text.Substring(0, length);
8	8		}
9	9		}
10	10
11	11		public class Labels
12	12		{
13	13		public string Short(string name)
14	14		{
15		−	return name.Truncate(10) + TextExtensions.Truncate(name, 3);
	15	+	return name.Truncate(10, "...") + TextExtensions.Truncate(name, 3, "...");
16	16		}
17	17		}

1		using System;
2
3		namespace Shop;
4
5		public class Item : IComparable<Item>
6		{
7		public int Rank { get; set; }
8
9		public int CompareTo(Item other)
10		{
11		return Rank.CompareTo(other.Rank);
12		}
13		}

1	1		namespace Shop;
2	2
3	3		public static class Choice
4	4		{
5		−	public static T Pick<T>(bool preferFirst, T first, T second)
	5	+	public static T Pick<T>(T first, T second, bool preferFirst)
6	6		{
7	7		return preferFirst ? first : second;
8	8		}
9	9		}
10	10
11	11		public class Menu
12	12		{
13	13		public string Main()
14	14		{
15		−	return Choice.Pick(true, "soup", "salad") + Choice.Pick<int>(false, 1, 2);
	15	+	return Choice.Pick("soup", "salad", true) + Choice.Pick<int>(1, 2, false);
16	16		}
17	17		}

1	1		namespace Shop;
2	2
3	3		public class Quote
4	4		{
5	5		public decimal Price(IShipping shipping, Courier courier)
6	6		{
7		−	return shipping.Cost(1.5m, "EU") + courier.Cost(2m, "US");
	7	+	return shipping.Cost("EU", 1.5m) + courier.Cost("US", 2m);
8	8		}
9	9		}

1	1		namespace Shop;
2	2
3	3		public interface IShipping
4	4		{
5		−	decimal Cost(decimal weight, string region);
	5	+	decimal Cost(string region, decimal weight);
6	6		}
7	7
8	8		public class Courier : IShipping
9	9		{
10		−	public decimal Cost(decimal weight, string region)
	10	+	public decimal Cost(string region, decimal weight)
11	11		{
12	12		return weight * 2m;
13	13		}
14	14		}
15	15
16	16		public class Post : IShipping
17	17		{
18		−	decimal IShipping.Cost(decimal weight, string region)
	18	+	decimal IShipping.Cost(string region, decimal weight)
19	19		{
20	20		return region == "EU" ? weight : weight * 3m;
21	21		}
22	22		}

1	1		namespace Shop;
2	2
3	3		public class Mailer
4	4		{
5		−	public string Compose(string to, string subject, bool urgent = false, string footer = "")
	5	+	public string Compose(string subject, string to, int priority = 0, bool urgent = false, string footer = "")
6	6		{
7	7		return to + subject + urgent + footer;
8	8		}
9	9
10	10		public void Send()
11	11		{
12		−	Compose("a@example.com", "Hello");
	12	+	Compose("Hello", "a@example.com");
13	13		Compose(subject: "Hi", to: "b@example.com");
14		−	Compose("c@example.com", "Report", footer: "Thanks");
15		−	Compose("d@example.com", "Memo", true);
	14	+	Compose("Report", "c@example.com", footer: "Thanks");
	15	+	Compose("Memo", "d@example.com", urgent: true);
16	16		}
17	17		}

1	1		namespace Shop;
2	2
3	3		public class Geometry
4	4		{
5	5		public int Area(int side)
6	6		{
7	7		return Area(side, side);
8	8		}
9	9
10		−	public int Area(int width, int height)
	10	+	public int Area(int height, int width)
11	11		{
12	12		return width * height;
13	13		}
14	14
15	15		public int Total()
16	16		{
17		−	return Area(3) + Area(4, 5);
	17	+	return Area(3) + Area(5, 4);
18	18		}
19	19		}

1	1		namespace Shop;
2	2
3	3		public class Notifier
4	4		{
5		−	public virtual string Format(string message, int level)
	5	+	public virtual string Format(string message, int level, string channel)
6	6		{
7	7		return level + ": " + message;
8	8		}
9	9		}
10	10
11	11		public class LoudNotifier : Notifier
12	12		{
13		−	public override string Format(string message, int level)
	13	+	public override string Format(string message, int level, string channel)
14	14		{
15		−	return base.Format(message.ToUpperInvariant(), level) + "!";
	15	+	return base.Format(message.ToUpperInvariant(), level, "email") + "!";
16	16		}
17	17		}
18	18
19	19		public class Alerts
20	20		{
21	21		public string Raise(Notifier notifier)
22	22		{
23		−	return notifier.Format("disk full", 2);
	23	+	return notifier.Format("disk full", 2, "email");
24	24		}
25	25		}

1	1		namespace Shop;
2	2
3	3		public class Logger
4	4		{
5		−	public string Log(string format, params object[] values)
	5	+	public string Log(int level, string format, params object[] values)
6	6		{
7	7		return string.Format(format, values);
8	8		}
9	9
10	10		public string Run()
11	11		{
12		−	return Log("{0} {1}", 1, 2) + Log("none");
	12	+	return Log(0, "{0} {1}", 1, 2) + Log(0, "none");
13	13		}
14	14		}

1		using System;
2
3		namespace Shop;
4
5		public class Calculator
6		{
7		public int Add(int a, int b)
8		{
9		return a + b;
10		}
11
12		public Func<int, int, int> Operation()
13		{
14		return Add;
15		}
16		}

1	1		namespace Shop;
2	2
3	3		public class Greeter
4	4		{
5		−	public string Greet(string name)
	5	+	public string Greet(string name, string? title)
6	6		{
7	7		return "Hello " + name;
8	8		}
9	9
10	10		public string Welcome(string? nickname)
11	11		{
12		−	return Greet(nickname ?? "friend");
	12	+	return Greet(nickname ?? "friend", null);
13	13		}
14	14		}

1	1		namespace Shop;
2	2
3	3		public class Invoice
4	4		{
5	5		/// <summary>Builds a line.</summary>
6	6		public string Line(
	7	+	int quantity,
7	8		string product, // what was sold
8		−	int quantity,
9	9		decimal price)
10	10		{
11	11		return product + quantity + price;
12	12		}
13	13
14	14		public string Print()
15	15		{
16	16		// two line items
17	17		return Line(
	18	+	2,
18	19		"pen", // product
19		−	2,
20		−	1.5m) + Line("cup", /* count */ 1, 2m);
	20	+	1.5m) + Line(/* count */ 1, "cup", 2m);
21	21		}
22	22		}

1	1		namespace Shop;
2	2
3	3		public class Report
4	4		{
5		−	public string Title(string name, int width)
	5	+	public string Title(string name)
6	6		{
7	7		return name.ToUpperInvariant();
8	8		}
9	9
10	10		public string Header()
11	11		{
12		−	return Title("sales", 80);
	12	+	return Title("sales");
13	13		}
14	14		}

`parameters`	`[{"name": "point", "type": "Point", "value": "new Point(3, 4)"}]`
`replacements`	`{"x": "point.X", "y": "point.Y"}`

1	1		using System;
2	2
3	3		namespace Geometry
4	4		{
5	5		public record Point(int X, int Y);
6	6
7	7		public class Grid
8	8		{
9		−	public double DistanceFromOrigin(int x, int y)
	9	+	public double DistanceFromOrigin(Point point)
10	10		{
11		−	return Math.Sqrt(x * x + y * y);
	11	+	return Math.Sqrt(point.X * point.X + point.Y * point.Y);
12	12		}
13	13
14	14		public double Sample()
15	15		{
16		−	return DistanceFromOrigin(3, 4);
	16	+	return DistanceFromOrigin(new Point(3, 4));
17	17		}
18	18		}
19	19		}

`parameters`	`[{"name": "max"}, {"name": "limits", "type": "Limits", "value": "new Limits(0)"}]`
`replacements`	`{"value": "limits.Min"}`

1		namespace Geometry
2		{
3		public record Limits(int Min);
4
5		public class Grid
6		{
7		public int Clamp(int value, int max)
8		{
9		if (value > max)
10		value = max;
11		return value;
12		}
13
14		public int Sample()
15		{
16		return Clamp(12, 10);
17		}
18		}
19		}

Change Signature

Arguments

Precondition

Transformation

Preserved

Limitations

Error codes

Cases

#add-parameter-across-files

#constructor

#duplicate-parameter-rejected

#extension-method

#extension-this-moved-rejected

#external-member-rejected

#generic-method

#interface-and-implementations

#method-group-rejected

#missing-value-rejected

#named-and-omitted-arguments

#nullable-parameter

#optional-before-required-rejected

#overloads

#override-hierarchy

#params-array

#params-not-last-rejected

#preserves-trivia

#remove-parameter

#removed-parameter-in-use-rejected

#reorder-parameters

#replace-removed-parameter-uses

#replaced-parameter-assigned-rejected

#unknown-parameter-rejected