Proposal: Coding Style, File Naming Conventions and other codding stuff

[miogds]

This proposal is intended as an open discussion for improving and aligning our coding style, file naming conventions and other coding stuff. This aims to gather feedback from everyone, especially those with coding experience, so we can outline the pros and cons and refine our standards over time.

Each idea below is presented as a standalone discussion point.

Please reply directly under each point / comment with your pros, cons, and suggestions so we can keep the discussion structured.

The goal always is to improve readability of the code

[miogds]

Global functions

I’ve been reorganizing the code: removing global variables, adding new structures and configurations, and preparing to extend the engine functionality to support the editor. However, I found it confusing to separate functions because the global functions are written in the same style as methods/member functions inside classes or structs.

Current Issue

In my own code style, I prefer to distinguish between them at a glance. For example:

• Global functions, classes, structs, enums, etc. → Start with an uppercase letter.
• Methods inside classes/structs → Start with a lowercase letter.

This convention makes it much easier for me to follow the code and immediately recognize whether a function is global or a member method.

Question

What do you think?

[untoldengine]

Thanks for raising this — I can see why having globals start with uppercase might make them easier to spot at a glance. After some thought though, I think we should stick with the official Swift naming conventions:

• Types → UpperCamelCase
• Functions (including globals) → lowerCamelCase
• Variables and properties → lowerCamelCase

The main reason is that this keeps us consistent with the Swift standard library and Apple frameworks (print(), min(), etc.). It also means we can rely on tools like SwiftFormat to enforce style automatically, without us fighting against the formatter.

I’ll also be going over the codebase to make sure I haven’t been using the wrong format for Types, so everything stays consistent.

That said, I definitely appreciate the perspective — naming is always a balancing act between readability and convention. Maybe we can experiment with other approaches to improve clarity. For example, we could come up with our own file name prefix or convention that hints whether something is a global function or a method (e.g., for methods, using a prefix like m_functionName). This way, we’d still follow Swift norms while making the distinction more explicit if needed.

[miogds]

📂 File Naming Conventions

While working on creating new files recently, I ran into several cases where I couldn’t immediately tell if a file contained a subclass definition or an extension. Since both types of files are currently named in the same style, the distinction wasn’t obvious until I actually opened the file and looked at the contents.

Subclasses

• Rule: Concatenate the base class name with the subclass name.
• Example: CameraNode.swift
• ✅ We already follow this convention consistently today.

Extensions

• Rule: Use a plus sign (+) to indicate added functionality.
• Example: Camera+Movement.swift
• ⚠️ Currently, we don't apply this rule. The way I name extensions likely comes from old Objective-C habits.

Why?

This convention improves readability by distinguishing between new subclasses and extensions at a glance.
It also helps keep the file structure organized and predictable.

Question

What do you all think?

[miogds]

Use Smaller, More Focused Files

From my background in embedded systems and Unix kernel development, I've seen how breaking code into small, purpose-driven files keeps things organized, easier to read, and more maintainable. Large files mix concerns and become harder to work with over time.

Recommendation

• Favor creating smaller files with clear responsibilities.
• Apply this gradually:
  • New code → create new files for distinct functionality.
  • Existing code → split large files when refactoring naturally happens.

Benefits

• Easier to read and review.
• Fewer merge conflicts.
• Clearer ownership of code areas.
• Supports multiple contributors working in parallel without stepping on each other's changes.
• Scales better as the project grows.

Note

This is not a strict rule during the learning stage. Early on, larger files are natural when abstractions aren't clear yet. The proposal is simply a guideline to keep in mind, so that as we gain clarity, we refactor toward smaller, modular files.

Question

What do you all think?

[untoldengine]

I totally agree with this. I will be making changes to files in the utils folder. They need to be broken up further.

[untoldengine]

I generally agree with these coding style suggestions. I’ll need to think a bit more about the “+” for extensions. Is that something Swift developers typically use? Coming from the C/C++ world, I haven’t really seen that before, so I’ll give you a clear answer tomorrow.

For the changes, I suggest we approach them in an organized way: for example, start with Global Functions → push PR, then move on to Extensions → push PR, and so on. My thought is that we should do this after the next release. I’d like to get the documentation updated, merge in your next PRs and mine, and then do a v0.3.0 release before tackling these style adjustments.

Also, I currently use SwiftFormat (explained here:
https://github.com/untoldengine/UntoldEngine/blob/master/docs/Formatting.md), and I think it makes sense to make that mandatory so we keep consistency across contributions.

What do you think?

[miogds]

The + is typically for the Swift developers that came from Objective-C developers before. Then new developers don't use it as they don't know. Inside Apple, they still use the same patterns as Obj-C., like the global functions.

All I explain is just to start a discussion; we don´t need to follow it now. Over my years, more than 35 and working on different areas, I like that the code should be clear, focus on knowing as much information as possible just by looking at the function so it's easy to follow, especially if I'm reading from another developer.

It depends on the language; I follow different rules about naming, convention, etc., to be more friendly for the developer in that language, but it depends on the rules; if usually that language is common to use one pattern, but I consider the readability is not good enough, I don't follow it.

So this is just an open discussion to think about formatting for the future, just to keep the discussion open as we go moving forward.

[miogds]

I agree with using Swift format. I use it in my projects too, but with some modifications, especially about spacing, most of the languages don't take advantage of the vertical selection tool available in all IDEs.

[untoldengine]

Hi, let's start using "+" to imply "extension". I was thinking of using ".", but after learning that "+" was commonly used in Obj-C, I decided to use "+" instead.

Thank you