• RSS Feed

Change Signature

Refactoring with Change Signature is a convenient way to change the calling signature of a function or method. Changing a signature can make symbol names clearer, methods more valuable to developers, and methods more likely to be used correctly.

You can change signature from an implementation, declaration or reference, letting you refactor without interrupting your normal flow of editing. Change Signature also updates all references to a function or method. For C/C++, the refactoring changes both declarations and implementations, ensuring the two constructs remain consistent.

Changes to signature can be undone (Ctrl+Z), even when changes are made in multiple files.

Change Signature is often invoked after Extract Method.

Visual Assist versus Visual Studio

Change Signature is built into Visual Studio 2017.

Access

Change Signature is available from the name of a function or method, not from a parameter list. Invoke the command via the context menu of the text editor, or via the Quick Refactoring Menu (Shift+Alt+Q). 

Access is also available in several tool windows, including the HCB component of the VA View and the VA Outline.

After invoking Change Signature, a dialog opens containing a current signature and all call sites that can be changed.

Modify the signature in the field edit control to reflect your preferred signature. Make sure your change maintains proper syntax so Visual Assist understands correctly what you intend to modify. You can change one or more items in a signature using a single operation as long as there is no ambiguity in your request.

A rename of a parameter changes only a declaration and implementation.

An addition of a parameter changes declaration, implementation, and call sites.

If you want to change all call sites, accept the new signature and Visual Assist updates your declaration, implementation, and call sites. If you want to change a limited number of sites, select/deselect the checkboxes associated with files and call sites before accepting the new signature. You can select/deselect at the scope of project, file, and call-site.

Signature Parts

You can use Change Signature to modify all parts of a signature, including:

  • Method name
  • Return type
  • Visibility
  • Parameter names
  • Parameter types
  • Parameter order
  • Number of parameters
  • Qualifiers

Change Method Name

Changing only the name of a method with Change Signature is equivalent refactoring with Rename. You can use either command for the simple operation.

Change Return Type

Changing a return type does not change code accepting the return values from calls to the method. If you must modify code to accept a new return type, e.g. to insert a cast, use Find References after Change Signature to locate your call sites.

For C/C++, refactoring to change return type or qualifiers changes both declaration and implementation.

Change Parameters

You can change parameter names and types, and reorder parameters, with Change Signature. Visual Assist evaluates old and new parameter names and types to determine the desired outcome of a refactoring. You can affect multiple changes in a single operation as long as your request is unambiguous.

If you change more than one parameter name in a function or method, Visual Assist generally assumes your order of parameters remains constant. If you rearrange the order of multiple parameters, and change their names, you should complete the refactoring in two commands—change names in one refactoring and change order in another.

Rename multiple parameters before reordering them so your change is unambiguous.

If your change is ambiguous, Visual Assist displays a notice and disables the OK button.

If you have to make a complex change, e.g. when renaming and changing types of all parameters, do so in a series of simple, smaller changes.

Use Change Signature, instead of Rename, to alter a parameter name in C/C++ so that parameter names in declarations and implementations remain consistent. If you rename a parameter using the Rename command, only the signature and body of an implementation are updated; the declaration is untouched. 

Add a Parameter

If you add a parameter to a signature, Visual Assist will prompt for a parameter value to be inserted in the call sites. The default value passed is "TODO", which serves as a gentle reminder to fix the call sites; your code won't compile until you do. 

Modify the call sites on a case-by-case basis using the results of Find References that is launched automatically after a change.

If you use VA Hashtags for navigation, consider changing the default parameter to one. Then, you can use the VA Hashtag to easily find and navigate among the call sites that need to be updated.

If there exists a parameter value that is suitable for all, or most, call sites, specify that value. After the refactoring, update only the call sites that should pass a different value.

If you assign a default value in the signature, Visual Assist will not update any of the call sites. After the refactoring, update only the call sites that should use a value other than the default.

Change Visibility and Qualifiers

You can add modifiers—such as static, virtual, and const—and change visibility in C#. You can add modifiers in C/C++, but you cannot use Change Signature to alter visibility in C/C++.

Change in an Inheritance Chain

Visual Assist can change signatures in inherited references from parent classes and overridden references in child classes. The list of call sites in the Change Signature dialog is updated when you change the setting.

Change in Comment and String References

You can broaden scope to include hits in relevant comments and strings. Visual Assist uses heuristics to determine which hits are relevant, e.g. proximity of a signature to non-comment and non-string signatures.

Change in all Projects

You can restrict the list of call sites to the current project, or expand it to include all projects in your solution. The list of call sites in the Change Signature dialog is updated when you change the setting.

Call sites in the Change Signature dialog window are always grouped by file. Project nodes appear in the dialog when you search for call sites in all projects.

The setting to search in all projects is shared with the Find References and Rename commands. If you restrict Change Signature to the current project, the scope of the next Find References or Rename is restricted to the current project as well. If you broaden the scope of Change Signature to all projects, the next invocation of Find References or Rename will also search all projects. The shared setting prevents you from inadvertently refactoring references inconsistent with those you review using Find References.

Formatting

Change Signature attempts to retain comments and white space in parameter lists.

Change Signature refactors implementations so they conform to the format defined by the VA Snippet for Create Implementation.

Restrictions

Change Signature does not let you alter a function or method found using stable directories, e.g. from MFC or a 3rd party library.

Change Signature is not available on overloaded methods.

Visual C++ 6.0

Undo is not available in a single operation. Issue multiple undo commands (Ctrl+Z) to reverse a single change of signature.