GDScript Coding Conventions: Best Practices for Readable and Maintainable Code

sepTN

Hello fellow Godot developers!

Today, I want to dive into an essential topic that often gets overlooked but plays a crucial role in creating clean, readable, and maintainable GDScript code: coding conventions. Consistent coding conventions not only make your code more organized but also contribute to the overall productivity and collaboration within your development team. So, let's explore some best practices for writing GDScript code, including naming conventions for assets, scenes, and nodes.

gdscript coding style

Introduction to GDScript Coding Conventions

Coding conventions are a set of guidelines and rules that developers follow to maintain consistency in their codebase. They help create a standardized format, making it easier for developers to understand each other's code and contribute effectively. GDScript, as a flexible and Python-like scripting language, allows developers to write code in various ways. However, sticking to a common set of conventions enhances code quality and makes your projects more robust.

In this post, we'll cover some general coding conventions and delve into naming conventions for variables, functions, classes, and more. Additionally, we'll explore how to apply these conventions to assets, scenes, and nodes in your Godot projects.

General Coding Conventions

Indentation

Consistent indentation is vital for code readability. GDScript generally uses tabs for indentation. Avoid using
spaces, as different editors might interpret them differently.

# Bad indentation example
func calculate_score(score_value: int) -> int:
    if score_value > 100:
        return score_value * 2
    else:
        return score_value

# Good indentation example (using tabs)
func calculate_score(score_value: int) -> int:
	if score_value > 100:
		return score_value * 2
	else:
		return score_value

Line Length

To enhance code readability, aim to keep your lines of code within a reasonable length. A common practice is to limit lines to around 80 characters. If a line becomes too long, consider breaking it into multiple lines or using parentheses for better formatting.

# Good line length example
func _ready():
	var message = "Hello, Godot developers! Welcome to our community."
	print(message)

# Bad line length example
func _ready(): var message = "Hello, Godot developers! Welcome to our community."; print(message)

Whitespace

Use whitespace judiciously to separate different parts of your code and improve readability. Add spaces after commas, around operators, and between function arguments.

# Good use of whitespace example
func calculate_total_score(score1: int, score2: int) -> int:
	return score1 + score2

# Bad use of whitespace example
func calculate_total_score(score1:int,score2:int)->int:
	return score1+score2

Comments

Add comments to explain your code and its purpose. Well-commented code helps other developers, including your future self, understand the logic and functionality of your code.

# Good use of comments example
# This function calculates the total score by adding two individual scores.
func calc_total(s1: int, s2: int) -> int:
	return s1 + s2

# Bad use of comments example
func calc_total(s1: int, s2: int) -> int:
	return s1 + s2

Nevertheless, the best code is the code that doesn't require comments as it is innately self explanatory.

func calculate_total_score(score1: int, score2: int) -> int:
	return score1 + score2

Naming Conventions

Variables and Constants

Use descriptive names for variables and constants that indicate their purpose. Names should be in lowercase, with words separated by underscores.

# Good variable naming example
var player_health: int = 100
const MAX_ENEMIES: int = 10

# Bad variable naming example
var p: int = 100
const max: int = 10

Functions and Methods

Function and method names should also be descriptive and use lowercase letters with underscores to separate words.

# Good function naming example
func calculate_score(score_value: int) -> int:
	return score_value * 2

# Bad function naming example
func clc(score: int) -> int:
	return score * 2

Classes and Enums

Use PascalCase for class and enum names. Class names should be nouns, while enum names should be singular nouns.

# Good class and enum naming example
class Player:
	enum Direction { UP, DOWN, LEFT, RIGHT }

# Bad class and enum naming example
class playeR:
	enum direction { UP, DOWN, LEFT, RIGHT }

Naming Conventions for Assets and Scenes

Assets

When naming assets, camel_case, use lowercase letters and separate words with underscores. Be descriptive and use meaningful names that indicate the asset's purpose. The reason why we use all lowercase letters is that each platforms have different ways in treating uppercase and lowercase in file names.

# Good asset naming example
main_room.tscn
main_room.gd
background_image.png
enemy_sprite.png
jump_sound.wav

# Bad asset naming example
mainRoom.tscn
mainRoom.gd
bg.png
spr1.png
sound1.wav

Nodes

Nodes in scenes should follow PascalCase conventions. Choose descriptive names that represent the node's functionality.

# Good node naming example
PlayerCharacter
EnemySpawner
ScoreLabel

# Bad node naming example
Player
Node2D
Label

Coding Style

Consistency is key when it comes to coding style. Ensure that you and your team members follow the same conventions throughout your project. Adopting a consistent coding style improves readability and makes your code look professional.

In addition to the conventions mentioned above, consider adopting the following practices:

Use Meaningful Names: Always choose meaningful names for variables, functions, classes, and nodes. Avoid single-letter or vague names that might confuse other developers.
Be Mindful of Abbreviations: While abbreviations can save typing, be cautious with them. Avoid using obscure or ambiguous abbreviations that might not be immediately understandable.
Avoid Magic Numbers: Instead of using literal values in your code, assign them to constants with descriptive names. This improves code readability and makes it easier to maintain.
Limit Function Length: Aim to keep your functions short and focused. Long functions can become difficult to manage and understand.
Organize Code Logically: Structure your code in a logical manner, breaking it into meaningful sections or using comments to group related code together.

Code Reusability

An essential benefit of following coding conventions is that it promotes code reusability. When your code is well-organized and follows consistent conventions, you can easily reuse functions, methods, and classes across different projects.

By applying the same conventions to your assets, scenes, and nodes, you can also streamline your workflow when working with Godot Engine. Consistent naming and organization help you find and manage resources more efficiently, resulting in a smoother development process.

Summary

Coding conventions are an invaluable tool for any Godot developer seeking to create clean, readable, and maintainable code. In this post, we explored some general coding conventions, including indentation, line length, whitespace, and commenting. We also discussed naming conventions for variables, functions, classes, enums, assets, scenes, and nodes.

Adopting coding conventions in your projects enhances code quality, increases collaboration within your team, and facilitates code reuse. Consistent naming and organization make it easier for you and other developers to understand and contribute to the codebase effectively.

Remember that while coding conventions offer a set of guidelines, they are not set in stone. You can adapt them to suit your team's preferences and requirements. What matters most is that you and your team members follow the same conventions consistently throughout your projects.

Happy coding, and may your Godot projects thrive with clean and maintainable code!

Godot Community