Reconsider the use of 2 in conversion function names

Open Beginner friendly
  • Is something wrong?
#7 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
63/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Active
Tech stack
matlab
Domain
documentation

Research direction

Start with the repository’s MATLAB coding guidelines and locate the “Function name style” section quoted in the issue. Review the existing recommendation and the proposed alternatives, then update the guidance if the maintainers accept the change. Done means the conversion naming recommendation reflects the decision and remains consistent with the surrounding style guidance.

Written by the indexing model from the issue text.

Description

The MATLAB coding guidelines currently state the following under Function name style:

Name functions and methods using a verb or verb phrase to convey the action performed. Alternatively, name functions and methods using a noun or noun phrase if the noun describes the thing being created. Use the numeral "2" in the name of a conversion function. Use the prefix "is" or "has" for a function whose primary output is a logical value. Use complementary names for functions with complementary operations (e.g., start/stop, create/destroy, etc.).

I would like to suggest reconsidering the recommendation to use the numeral 2 in conversion function names.
The type2type convention feels dated and, more importantly, can reduce readability. Using 2 as a substitute for "to" makes names less natural to read and becomes particularly awkward when the type names themselves contain numbers. For example, consider:

myByte = uint82byte(myUint8);

versus:

myByte = uint8ToByte(myUint8);

or:

myByte = byteFromUint8(myUint8);

I find the last form the clearest because it reads naturally as "byte from uint8" and makes the direction of the conversion immediately apparent.
This convention also maps naturally to an object-oriented API. For example, the same operation could conceptually be expressed as:

myByte = Byte.FromUint8(myUint8);

The standalone function name byteFromUint8 follows directly from that same naming pattern.

Beyond aesthetics, avoiding 2 would also eliminate potentially confusing names such as uint82byte, where the 8 belongs to the source type and the 2 represents the word "to".
My suggestion is therefore to reconsider the requirement to use 2 for conversion functions and instead recommend descriptive conversion names such as:

  • targetFromSource, e.g. byteFromUint8
  • sourceToTarget, e.g. uint8ToByte

Of the two, I would favor targetFromSource because it emphasizes what the function produces and reads naturally at the call site.

Dominant language
No language data
Stars
143
Forks
11
No merged PRs in 30d

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from mathworks/MATLAB-Coding-Guidelines

All issues in mathworks/MATLAB-Coding-Guidelines

Similar issues

More Documentation issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.