5.20.8 Naming conventions for new functions

When adding new functions that replace or extend existing functions, use the following naming conventions.

Note:

  • Only add new functions if the same effect cannot be achieved by extending an existing function with new return value members or with new optional arguments.
  • All orthogonal changes or additions can be achieved with new optional arguments. Adding new functions to replace or enhance existing ones is not necessary.

Assuming the existing function is called breakpoint_set(), and a new non-orthogonal feature, foo, must be added, which cannot be supported by extending breakpoint_set() with optional arguments, for example breakpoint_set(enableFoo=True, …), new versions of this function should be named, in the following order, from most to least preferred:

breakpoint_setFoo()
Use this when Foo is a suitable description of the new non-orthogonal feature. If the feature is orthogonal to existing functionality, an argument foo={"space":42, "index":6} or enableFoo=True should be added to the existing breakpoint_set() function, rather than introducing a new function.
breakpoint_set_armCortexA53()
Use this when the behavior is processor-specific, and cannot be generalized. Generalizing is preferred if possible, preferably in an orthogonal way, so that introducing a new function is not necessary. For example:
breakpoint_set(addressArmCortexA53UtlbTag=<something_very_complex>)
experimental_breakpoint_set_armCortexA53()
Use this when the function is experimental and should only be used by an experimental client.
breakpoint_foo()
Use this when the new functionality is breakpoint-related, but does not have set semantics but foo semantics instead.
foo_bar()
Use this when this is entirely new functionality, not related to breakpoints at all.
breakpoint_set2()
Use this when this function has the same semantics as breakpoint_set, but has a better interface with incompatible arguments or incompatible return value and therefore enhancing the argument list or return value is not an option.

See also 5.2 Naming conventions for general naming conventions.

Non-ConfidentialPDF file icon PDF version101196_0100_03_en
Copyright © 2018, 2019 Arm Limited or its affiliates. All rights reserved.