Code Style Guide

Coding conventions and best practices for the Funkin’ repository

This guide covers code formatting standards to maintain consistency throughout the Friday Night Funkin’ codebase.

Following these conventions makes the repo easier to maintain and helps your pull requests get merged faster.

IDE Setup

Visual Studio Code (Recommended)

The repository contains VSCode configurations that automatically format your code.

1. Install Visual Studio Code

   Download from code.visualstudio.com

2. Install Haxe extension

   Install the official Haxe extension from the VSCode marketplace.

   The extension will use the repo’s hxformat.json to format code automatically.

3. Enable Format on Save

   In VSCode settings, enable Format on Save for automatic formatting.

   {
     "editor.formatOnSave": true
   }
   
4. Install CodeDox (optional)

   The CodeDox extension provides JavaDoc-style comment support for Haxe.

   This makes it easy to document functions properly.

VSCode is the only IDE with good Haxe tooling. Other IDEs may not support the language well.

Whitespace and Indentation

The Haxe extension uses the repo’s hxformat.json file to automatically format code.

Key formatting rules:

• Indentation: 2 spaces (not tabs)
• Line endings: LF (Unix-style)
• Trailing whitespace: Removed automatically

View hxformat.json configuration

The repository’s hxformat.json file controls all formatting rules. VSCode will apply these automatically when you save a file.

Naming Conventions

Variables and Functions

Use lowerCamelCase for variables and functions:

Good ✓

var playerHealth:Float = 100;
var currentSongPosition:Int = 0;

function updateHealthBar():Void
{
  // ...
}

function calculateAccuracy(notesHit:Int, totalNotes:Int):Float
{
  return notesHit / totalNotes;
}

Classes and Types

Use UpperCamelCase for classes, interfaces, and type names:

class PlayState extends MusicBeatState
{
  // ...
}

interface ISongLoader
{
  // ...
}

enum NoteDirection
{
  LEFT;
  DOWN;
  UP;
  RIGHT;
}

Constants

Use UPPER_SNAKE_CASE for compile-time constants:

static final DEFAULT_HEALTH:Float = 100;
static final MAX_COMBO:Int = 9999;
static final GAME_VERSION:String = "0.8.3";

Descriptive Names

Use descriptive names over short abbreviations. There’s no penalty for longer names.

Good ✓

var playerHealth:Float;
var enemyPosition:FlxPoint;
var songTimeInMilliseconds:Float;

Code Comments

Function Documentation

Use JavaDoc-style comments for all public functions:

/**
 * Finds the largest deviation from the desired time inside this VoicesGroup.
 *
 * @param targetTime The time to check against.
 *                   If none is provided, it checks the time of all members 
 *                   against the first member of this VoicesGroup.
 * @return The largest deviation from the target time found.
 */
public function checkSyncError(?targetTime:Float):Float
{
  // Implementation...
}

Benefits of JavaDoc comments:

• Automatic documentation generation
• IDE tooltips show function info
• Clear parameter and return value descriptions

Inline Comments

DO ✓

Good inline comments:

// Don't go back in time to before the song started.
targetTimeMs = Math.max(0, targetTimeMs);

// Prevent the volume from being wrong.
FlxG.sound.music.volume = 1.0;
if (FlxG.sound.music.fadeTween != null) FlxG.sound.music.fadeTween.cancel();

What makes these good:

• Explain the “why”, not the “what”
• Clear and concise
• Proper capitalization and punctuation

DON'T ✗

Bad inline comments:

// set the volume to 1
FlxG.sound.music.volume = 1.0;

// cancel the fade tween if it exists
if (FlxG.sound.music.fadeTween != null) FlxG.sound.music.fadeTween.cancel();

// I hate this function - [GitHub username]
resyncVocals();

// lol this is broken idk why
// functionThatWasntHereBeforeThisPRorSomethingIdKLOL();

What makes these bad:

• Stating the obvious
• Personal opinions that don’t help
• Unclear or joke comments
• Lowercase sentences

Comment Guidelines

When to comment

Only leave comments when code needs explanation:

✓ Complex algorithms
✓ Non-obvious behavior
✓ Workarounds for known issues
✓ Important warnings

✗ Self-explanatory code
✗ Obvious variable assignments
✗ Every single line

Provide meaningful insight

Comments should explain:

• Why the code does something (not what it does)
• The purpose or reasoning behind a decision
• Edge cases being handled

// Good: Explains why
// A negative instrumental offset means the song skips 
// the first few milliseconds of the track.
FlxG.sound.music.play(true, Math.max(0, startTimestamp - offset));

// Bad: States the obvious
// Play the music
FlxG.sound.music.play();

Sign comments sparingly

Only sign your comments with your name when:

• Changes are complex and may require follow-up
• You’re introducing a temporary workaround
• Future developers might need to contact you

Don’t sign every comment — it adds clutter.

No Commented-Out Code

Do NOT leave commented-out code in the repository!

// Bad ✗
// var oldHealth:Float = 50;
// if (oldHealth < 0) doSomething();

var playerHealth:Float = 100;

Why?

• Makes files longer and harder to read
• Confusing for other developers
• Old code can be found in Git history if needed

Exceptions:

• Temporarily debugging (remove before committing)
• Documentation purposes (use clear explanations)

Imports

Imports should be:

• Placed at the top of the file
• Grouped together
• Sorted alphabetically
• Conditional imports at the end

Good ✓

import flixel.FlxSprite;
import flixel.math.FlxMath;
import flixel.util.FlxColor;
import haxe.format.JsonParser;
import openfl.Assets;
import openfl.geom.Matrix;

#if sys
import funkin.io.FileUtil;
import sys.io.File;
#end

Function Arguments

Optional vs Default Arguments

Do NOT use optional arguments (?) and default values together!

Good ✓

// Use optional for nullable types
function doSomething(?input:Int):Void
{
  if (input != null) trace(input);
}

// Use default for non-nullable with default value
function doSomethingElse(input:Int = 0):Void
{
  trace(input);
}

Guidelines:

• Use ?argument when the argument should be Null<T> and default to null
• Use argument = value when the argument should have a default value but not be nullable
• Never use both together

License Headers

Do NOT include license headers on individual files!

The main LICENSE.md file covers all code in the repository. Individual file headers are unnecessary and create clutter.

Quick Reference

Naming Cheat Sheet

Type	Convention	Example
Variables	lowerCamelCase	playerHealth
Functions	lowerCamelCase	calculateScore()
Classes	UpperCamelCase	PlayState
Interfaces	UpperCamelCase	ISongLoader
Enums	UpperCamelCase	NoteDirection
Constants	UPPER_SNAKE_CASE	MAX_HEALTH

Comment Cheat Sheet

✓ DO:

• Use JavaDoc for public functions
• Explain why, not what
• Be clear and concise
• Use proper grammar and punctuation

✗ DON’T:

• State the obvious
• Leave commented-out code
• Add personal opinions
• Use unclear abbreviations

VSCode Extensions

Recommended extensions for Haxe development:

Haxe

Official Haxe language support

CodeDox

JavaDoc-style documentation comments

EditorConfig

Automatic formatting settings

GitLens

Enhanced Git integration

Next Steps

Contributing Guide

Learn how to submit code

Compilation Guide

Set up your dev environment

Troubleshooting

Fix common issues

GitHub Repository

View the source code