Formatting the source code

• C++ and friends
  • Download Uncrustify
  • Add Uncrustify to PATH
  • Run Uncrustify manually
  • Run Uncrustify on every commit
  • Run Uncrustify in your IDE
• Other languages
  • New files
  • Existing files
• Editing without changing style
• Third-party code

C++ and friends

We have strict style guidelines for the C++ code, and any files written in similar languages like plain C or Objective C, but not to third-party code.

The guidelines are enforced in pull requests by the codestyle CI check, which uses Uncrustify to format the code, and gives an error if any style violations were detected.

You can save time by running Uncrustify on your local machine before you push code to GitHub.

Download Uncrustify

Make sure you get Uncrustify version 0.74, as this is the version used by the codestyle check.

• Windows: Download the official binary.
• MacOS & Linux: Compile the uncrustify-0.74.0 tag yourself (it's quite easy).

Warning

If you use the wrong version of Uncrustify (such as one installed via a package manager), your PR may fail the codestyle check, and your commits may show changes to areas of code that you weren't trying to edit.

Note: This can also happen if we update our version of Uncrustify and you're still using the old version.

Add Uncrustify to PATH

Once extracted/compiled, you need to add the directory of the uncrustify binary to your PATH environment variable, or move it to a directory that's already in PATH, or create a symlink in PATH that points to the binary's current location.

Run Uncrustify manually

You could use the scripts in tools/codestyle to run Uncrustify on a single file, a directory of files, or the entire repository. However, you'd have to repeat this each time you edit the code, so you're better off using the automatic methods given below.

Run Uncrustify on every commit

This method uses a Git hook to automatically run Uncrustify whenever you create a commit. This works regardless of how you edit the files, but you won't see the benefit in your IDE until you create a commit, and the files that were reformatted have to be recompiled on the next build. For best results, use this method in combination with running Uncrustify in your IDE.

Run this command once in MuseScore's source folder to enable our pre-commit hook:

# LINUX AND MACOS: SYMBOLIC LINK
ln -s ../../hooks/pre-commit .git/hooks/pre-commit

# WINDOWS: FAKE SYMBOLIC LINK
# Creates a Windows .lnk shortcut that simulates a symlink. It MUST be created by
# the `ln` command in Git Bash or MSYS. Other methods of creating a .lnk won't work.
MSYS=winsymlinks:lnk ln -s ../../hooks/pre-commit .git/hooks/pre-commit

# WINDOWS: REAL SYMBOLIC LINK
# These commands require Administrator privileges unless Developer mode is enabled.

# Git Bash with gsudo (or use plain sudo or Admin prompt)
MSYS=winsymlinks:nativestrict gsudo ln -s ../../hooks/pre-commit .git/hooks/pre-commit

# CMD (use Admin prompt or gsudo, not plain sudo)
mklink .git\hooks\pre-commit ..\..\hooks\pre-commit

# PowerShell (use Admin prompt or gsudo, not plain sudo)
cmd /c mklink .git\hooks\pre-commit ..\..\hooks\pre-commit

Now Git will run Uncrustify for you each time you commit code, so you never have to think about it!

If you need to disable the pre-commit hook later on, run this command:

# CMD and PowerShell
del .git\hooks\pre-commit

# Everything else (also works in PowerShell)
rm .git/hooks/pre-commit

Or you can disable the hook temporarily by passing the -n/--no-verify option to git commit.

Run Uncrustify in your IDE

Most IDEs provide an option to automatically format code each time you save a file. This means you don't have to create a commit to see the improvements, and since you're saving the file anyway, nothing has to be recompiled purely because of formatting changes. However, this method won't format files edited outside the IDE, so for best results you should use this method in combination with the pre-commit hook.

Run Uncrustify in Qt Creator

1. Go to Help (Mac: Qt Creator) → About Plugins → C++.
   1. Enable Beautifier (experimental).
   2. Click OK and restart Qt Creator.
2. Go to Edit (Mac: Qt Creator) → Preferences → Beautifier.
3. On the General tab:
   1. Enable Automatic Formatting on File Save.
   2. Below this, change the Tool dropdown to "Uncrustify".
4. On the Uncrustify tab:
   1. In Uncrustify command, enter the full path to your Uncrustify binary (or browse to it).
   2. Disable Use file uncrustify.cfg defined in project files.
   3. Enable Use file specific uncrustify.cfg and browse to tools/codestyle/uncrustify_musescore.cfg.

Run Uncrustify in VS Code

1. Install the "Uncrustify" extension.
2. Open VS Code Settings and find Uncrustify.
3. Set Config Path to /path/to/MuseScore/tools/codestyle/uncrustify_musescore.cfg
4. Go to Format.
5. Enable Editor: Format On Save.
6. Restart VS Code.

Other languages

We don't have automatic style checks for any languages besides C++ and friends, but we do have recommendations for other languages.

New files

We recommend that you enable the following settings in your IDE as the default for all newly created files:

• Encoding: UTF-8
• Line ending: Unix-style (LF - linefeed, \n)
• Indentation: 4 spaces (not tabs)
• Trim trailing whitespace
• Insert newline at end of file

In general, we recommend that you adopt whatever style conventions are commonly used in each language, or when there is no consensus, do whatever is most similar to our C++ style. The CodeGuidelines provide more explicit rules for certain languages.

Existing files

Existing files should continue to use whatever style is already most prevalent in that file. See Editing without changing style.

If you're rewriting substantial portions of a file anyway then you could consider reformatting the entire file to follow our recommendations for new files.

If you find several files that are not following the recommendations, you could consider reformatting them all in one big PR that is free of any semantic changes. Create a commit with the style change then add this commit's SHA to .git-blame-ignore-revs in a second commit on the same PR. Make sure you update the SHA when rebasing.

Similarly, if you want to move lots of files or rename a directory, it's best to do this in a separate PR that is free of other changes.

Editing without changing style

When making semantic changes, sometimes it's best to disable automatic formatting in your IDE so that the important changes are not obscured by lots of whitespace changes elsewhere in the file. This makes it easier for team members to review your PR.

In VS Code, you can use the shortcut Ctrl+K followed by Ctrl+Shift+S to save a file without reformatting it. Or you could edit the file in a simple text editor that doesn't support automatic formatting, such as Notepad or nano. Make sure you don't leave any trailing whitespace on the lines you edit.

Alternatively, you can allow your IDE to reformat the file, then you can filter out unwanted changes with git add -p [file]. When prompted by Git, type y to accept a change, n to reject it, s to split the change into smaller changes (if possible), or e to edit manually. This enables you to commit the semantic changes (with git commit), then you can use git checkout -- [file] to discard the unwanted style changes.

Third-party code

Ideally we wouldn't change third-party code at all, but sometimes it's necessary to make small changes in order to integrate it with MuseScore Studio. When we do this, it's important that we're able to compare our version to the original to see what we changed. This matters when it's time to update the third-party code to a newer version released by the upstream project.

To make this comparison straightforward, code borrowed from other open source projects must be committed verbatim. Any semantic changes must be made in separate commits after the initial import. No style changes are allowed.

To prevent our Uncrustify scripts from modifying these files, add an empty file called .untidy to the directory of the third-party library/module (which should be named after the library/module) or to the parent directory (which should be named thirdparty).

If you need to edit the third-party files, see editing without changing style.