[RFC]: use string interpolation in JavaScript benchmarks for the benchmark name (tracking issue)

[kgryte]

Instructions

1. Read the issue description below.
2. Read the issue comment which follows the description.
3. Search the code base for a package having a JavaScript benchmark which needs updating according to the description below.
4. Follow any additional guidance specified in this issue.

Description

This RFC proposes improving JavaScript benchmarks by moving away from string concatenation when specifying the benchmark name.

In short, this RFC seeks to refactor JavaScript benchmarks from, for example,

// ...

bench( pkg+':ndims='+ndims, function benchmark( b ) {
    // ...
});

// ...

to

// ...
var format = require( '@stdlib/string/format' );
// ...

bench( format( '%s:ndims=%d', pkg, ndims ), function benchmark( b ) {
    // ...
});

// ...

This refactoring is demonstrated in commit https://github.com/stdlib-js/stdlib/commit/086231d0bcfe2d4a9c4c932fc9333f8ac63c4087.

In particular, notice two things:

1. We add the import @stdlib/string/format. See the documentation for @stdlib/string/format for supported specifiers.
2. We replace string concatenation pkg+':ndims='+ndims with string interpolation format( '%s:ndims=%d', pkg, ndims ), where %s indicates to insert the package name (a string) and %d indicates to insert the number of dimensions (an integer).

By performing this refactoring, we facilitate

1. increased readability of benchmark names when reading benchmark source code.
2. easier debugging when encountering malformed benchmark names.
3. fine-tuned precision when interpolating numbers.
4. a future in which we can lint benchmark names which is not currently possible with the current string interpolation approach.

Steps

Given the relatively widespread practice of using string concatenation in benchmarks, this RFC aims to be an open call for any contributor wanting to contribute to the project to do the following:

0. Study the changes made in commit https://github.com/stdlib-js/stdlib/commit/086231d0bcfe2d4a9c4c932fc9333f8ac63c4087, as this commit contains the sorts of changes that we are looking for.
1. Ensure you have setup your local development environment by following the contributing guide, including make install-node-modules and make init.
2. Study the documentation for @stdlib/string/format.
3. Find a package containing a JavaScript benchmark which performs string concatenation when specifying the benchmark name. A possible global project search could use the regular expression bench\(\s*pkg\s*\+\s*'. From the search results, you should be able to find a package in need of updating.
4. Update the JavaScript benchmarks for that package, and only that package, to migrate to use string interpolation. JavaScript benchmarks can be found in the benchmarks/ folder of a package (if it exists). We are not interested in refactoring to use template strings. You should use @stdlib/string/format which supports a much greater range of specifiers.
5. Run JavaScript benchmarks locally using the command make benchmark BENCHMARKS_FILTER=".*/<package_name>/.*". For example, make benchmark BENCHMARKS_FILTER=".*/blas/ext/base/dfill/.*".
6. Verify that the formatted benchmark names in the benchmark output after refactoring match the benchmark names in the benchmark output prior to refactoring (meaning, verify that everything is formatted correctly and the original names are preserved).
7. Commit your changes.
8. Submit a PR updating the JavaScript benchmarks for that package (and only that package).
9. For the PR title, use the following template "bench: refactor to use string interpolation in <package_name>" where <package_name> is the name of the package you updated (e.g., blas/ext/base/dfill).
10. In the PR body/description, use the phrase "Resolves a part of ", and not "Resolves " or "Closes ", this issue, as this is a tracking issue and your PR only addresses one package of many needing updating.

Please do NOT make extraneous changes to benchmarks. We are not interested in changing benchmarks wholesale. We are only interested in replacing string concatenation logic with string interpolation when specifying a benchmark name.

Related Issues

None.

Questions

None.

Other

• If you are interested in working on this RFC, for each pull request, please only update the benchmarks for a single package.
• As mentioned above, please do NOT make extraneous changes to benchmarks. We are not interested in changing benchmarks wholesale. Nor are we interested in new "creative" changes. We are only interested in replacing string concatenation with string interpolation when specifying a benchmark name. Failure to match the behavior of the existing benchmarks and to respect this guidance will result in your PRs being automatically closed without review.
• As this is a "Good First Issue", you are strongly encouraged to avoid using AI when authoring your contribution. One of the primary intents of Good First Issues is to help introduce you to stdlib, its development environment, and the contribution process, as documented in the contributing guide. Most new contributors are unfamiliar with stdlib and its conventions, and thus fail to appropriately use LLMs and AI when authoring contributions, most often generating AI slop and leading to wasted time. Don't be one of those people. :) Take the time to manually author your first several PRs, and, once you are intimately familiar with project conventions, you can consider leveraging AI to augment your dev tasks.

Checklist

• [x] I have read and understood the Code of Conduct.
• [x] Searched for existing issues and pull requests.
• [x] The issue name begins with RFC:.

[stdlib-bot]

:wave: Important: PLEASE READ :wave:

This issue has been labeled as a good first issue and is available for anyone to work on.

If this is your first time contributing to an open source project, some aspects of the development process may seem unusual, arcane, or some combination of both.

1. You cannot "claim" issues. People new to open source often want to "claim" or be assigned an issue before beginning work. The typical rationale is that people want to avoid wasted work in the event that someone else ends up working the issue. However, this practice is not effective in open source, as it often leads to "issue squatting", in which an individual asks to be assigned, is granted their request, and then never ends up working on the issue. Accordingly, you are encouraged to communicate your intent to address this issue, ideally by providing a rough outline as to how you plan to address the issue or asking clarifying questions, but, at the end of the day, we will take running code and rough consensus in order to move forward quickly.
2. We have a very high bar for contributions. We have very high standards for contributions and expect all contributions—whether new features, tests, or documentation—to be rigorous, thorough, and complete. Once a pull request is merged into stdlib, that contribution immediately becomes the collective responsibility of all maintainers of stdlib. When we merge code into stdlib, we are saying that we, the maintainers, commit to reviewing subsequent changes and making bugfixes to the code. Hence, in order to ensure future maintainability, this naturally leads to a higher standard of contribution.

Before working on this issue and opening a pull request, please read the project's contributing guidelines. These guidelines and the associated development guide provide important information, including links to stdlib's Code of Conduct, license policy, and steps for setting up your local development environment.

To reiterate, we strongly encourage you to refer to our contributing guides before beginning work on this issue. Failure to follow our guidelines significantly decreases the likelihood that you'll successfully contribute to stdlib and may result in automatic closure of a pull request without review.

Setting up your local development environment is a critical first step, as doing so ensures that automated development processes for linting, license verification, and unit testing can run prior to authoring commits and pushing changes. If you would prefer to avoid manual setup, we provide pre-configured development containers for use locally or in GitHub Codespaces.

We place a high value on consistency throughout the stdlib codebase. We encourage you to closely examine other packages in stdlib and attempt to emulate the practices and conventions found therein.

• If you are attempting to contribute a new package, sometimes the best approach is to simply copy the contents of an existing package and then modify the minimum amount necessary to implement the feature (e.g., changing descriptions, parameter names, and implementation).
• If you are contributing tests, find a package implementing a similar feature and emulate the tests of that package.
• If you are updating documentation, examine several similar packages and emulate the content, style, and prose of those packages.

In short, the more effort you put in to ensure that your contribution looks and feels like stdlib—including variables names, bracket spacing, line breaks, etc—the more likely that your contribution will be reviewed and ultimately accepted. We encourage you to closely study the codebase before beginning work on this issue.

:sparkles: Thank you again for your interest in stdlib, and we look forward to reviewing your future contributions. :sparkles:

[DevForsure]

I would like to work on this RFC. My plan is to search for a package whose benchmarks use string concatenation for benchmark names, and refactor them using @stdlib/string/format as described. I will update only one package per PR.