Implement custom folding regions in the script editor

[jmb462]

Describe the project you are working on

A puzzle game with quite long scripts.

Describe the problem or limitation you are having in your project

When the script becomes to be too long, it's not easy to navigate into it.

Code folding helps a lot but yet we can just fold blocks based on indentation (or multiline comments).

Describe the feature / enhancement and how it helps to overcome the problem or limitation

As in a lot of other code editors, I propose to allow to define custom code region which could be folded.

A code region is not based on indentation, so it can contain several functions.

Describe how your proposal will work, with code, pseudo-code, mock-ups, and/or diagrams

I propose to use tag in comment.

#region name_of_region to define the beginning (name is optional)
#endregion to define the end of the region

In addition, I proposed to add an item in context menu Create Code Region, to automaticaly add tags surrounding the current selection and let user choose the name of the region.

Here is what it looks like:

I've already implemented this behaviour.
If you think this proposal deserve it, I would open a PR.

If this enhancement will not be used often, can it be worked around with a few lines of script?

Could often be used to organize long scripts.

Is there a reason why this should be core and not an add-on in the asset library?

One of the common feature of code editors, think it should be core.

[Calinou]

This can be worked around within functions by using if true: blocks.

[jmb462]

You can't use your workaround on functions or on variable declarations. It will still be indentation dependant.

This proposal allow to group several functions in one region.

[dalexeev]

I would prefer:

# BEGIN Optional name

...

# END

And add highlighting TODO, FIXME, etc.

[jmb462]

Why not @dalexeev, the tag have been choosen totally arbitrarily. We could choose a better tag name if the concept is ok.

Highlighting seems also important to me as the region may be hard to destinguish from regular comments without it.

[Paulb23]

Related engine issue, godotengine/godot/issues/19078

Just a note for implementation, this will have to be agnostic to the # symbol, as CodeEdit is designed to be generic for any language.

[jmb462]

It should always use the comments delimiter(s) of the script language.

[EricEzaM]

From C# at least, it has been somewhat established that regions are a bit of a code smell/anti-pattern.
https://softwareengineering.stackexchange.com/questions/53086/are-regions-an-antipattern-or-code-smell

I don't have a particular opinion on whether they should be added to GDScript/the editor, but just thought some might be interested in reading the link above.

[djrain]

From C# at least, it has been somewhat established that regions are a bit of a code smell/anti-pattern.

My view is that regions can serve a good purpose when used responsibly. And I don't think that potential misuse of a feature is a good reason not to have it.

I generally write good code, but I also just want to be able to focus on what I'm working on. If my script starts with a list of 20 variables that I don't really need to see anymore, it's just dumb to have these taking up half my screen space.

In particular, these would be useful with exported variables. It makes sense to hide these in a region so you don't accidentally edit the default value and expect the value to change on all instances, which I have done on numerous occasions.

Another valid use case might be separating in-editor code from runtime code.

[mikemherron]

From C# at least, it has been somewhat established that regions are a bit of a code smell/anti-pattern. https://softwareengineering.stackexchange.com/questions/53086/are-regions-an-antipattern-or-code-smell

To give a different perspective on this - I would agree with the above when working with C#, Java, C++, Go etc - but the difference is those languages have mature standalone editors with advanced refactoring tools and static type checking that makes it simple to extract method, extract class etc. to get rid of those code smells.

I'm currently working on project that is GDScript heavy, and those types of refactoring are really difficult and painful without better editor support. For that reason, I found myself searching for code folding ability in the editor and found this issue.

[PaganSeaWitch]

Regardless of whether or not regions are anti-patterns or code smell, I want them because I think they clean up scripts nicely.
People generally create regions anyway even if you cant fold them in the editor. For example each of my scripts are separated into the following regions.
Signals
Variables
Received Signal Functions
Regular Functions
And I would appreciate having the ability to quickly navigate between each of these regions.

[nhold]

I would agree with the above when working with C#, Java, C++, Go etc - but the difference is those languages have mature standalone editors with advanced refactoring tools and static type checking that makes it simple to extract method, extract class etc. to get rid of those code smells.

I'm currently working on project that is GDScript heavy, and those types of refactoring are really difficult and painful without better editor support. For that reason, I found myself searching for code folding ability in the editor and found this issue.

I think the takeaway from that is to improve the refactoring\code auto-completion of statically typed gdscript such that it rivals C#😄

[seocwen]

The usual arguments that regions lead to bad code is kind of moot for Godot. 83% of respondents on the 2021 survey say they program alone. Many projects in C# are designed around teams, where the use of regions can make it difficult to navigate and organize code since hidden code can be difficult to find and keep track of. But when you're coding alone, you should be able to organize your project to suit your own needs. If you don't like regions, don't use them. Some people like bigger classes, others rely on a folders they dump dozens or hundreds of files into, while others still prefer impossibly deep hierarchies of folders--they all sound garbage, but we all err one way or another compared to a group of peers.

Besides, the workflow in Godot is completely different. I'm often finding myself trying to juggle the file system, scenes , inspector, and scripts. This is especially true when working on scenes, resources, and scripts that all need to talk to each other. I feel like I spend an inordinate amount of time hunting for the last place I was in. This is especially true of support classes.

Personally, I find myself writing larger classes than I'd like to in Godot just because it's so painful to move around. If I'm working on a body of highly related code, I'd rather have as much of it as possible in one place than break it into support classes, because I dread having to dig through all of them trying to find the relevant component when the module's functionality doesn't intuitively divide. Moreover, Godot is so painful to refactor that it's often worth it to keep highly related modules in one place so things don't break all over when you go trying to split them up.

This being the reality of Godot, regions would be a significant quality of life improvement.

[rakkarage]

#region Name #endregion already works for gdscript when using vs or vscode as editor, would be nice to have the same in editor

[power-spike]

Regions are a part of the IDE / Editor for almost every other language I use. They are comments to the programming language.

This would be a great feature to have - it allows you to "skip" over code, and can help arrange code and stop large amounts of scrolling if you are working on a sub-function. (Godot doesn't have the ability to have more then one code window open at a time :().

Another VERY useful feature in other IDE's is the code structure.

I have attached an Image of Godot (3.5) and PHP Storm side by side. I can't even begin to explain how useful this is. I have marked a couple of the "region" sections with red brackets.

[drusepth]

Found this PR while googling a way to add regions to my code (a lot of 1-2 line functions for physics, kinematics, and movement helpers) and just wanted to voice support. This would be a great way to clean up code for anyone familiar with the feature from other languages while not getting in the way of anyone else unfamiliar with the feature. Things like being able to see your regions in the file outline a la the above screenshot would be even better; this would be a big boon to organizing large files, even if they're already written concisely and organized as well as possible. Not really a fan of putting things in if true: blocks just to be able to collapse them.

[atirut-w]

Found this PR while googling a way to add regions to my code (a lot of 1-2 line functions for physics, kinematics, and movement helpers) and just wanted to voice support. This would be a great way to clean up code for anyone familiar with the feature from other languages while not getting in the way of anyone else unfamiliar with the feature. Things like being able to see your regions in the file outline a la the above screenshot would be even better; this would be a big boon to organizing large files, even if they're already written concisely and organized as well as possible. Not really a fan of putting things in if true: blocks just to be able to collapse them.

Using them to "clean up" codes sounds like a code smell. I would love to use them to group functions, though.

[nhold]

Personally, I find myself writing larger classes than I'd like to in Godot just because it's so painful to move around.

Wouldn't you agree this is the real problem to solve? Writing classes in a harder to manage way, then having this feature to improve that seems odd to me - like the picture given by power-spike, the regions have 1 or 2 methods and could easily be other classes. I get it if it's purely aesthetic (When I close all my regions my class is clean!) but the same effect can occur with classes as they exist, which when coupled with the Quick Open... I think is very powerful.

There should be improvement in code intellisense, refactoring and project traversal before regions IMO.

[DatHacksGaming]

it's been over 4 years since this was proposed ... any reason it's still not included? It's a pretty standard feature in coding and the OP this even showed and easy method for it.

godotengine/godot#19078

[jmb462]

I finaly didn't post a PR of my work for two reasons :

• first feedbacks on my proposal didn't seem very enthousiastic (but seems that it gets more likes and interest with time).
• I'd have difficulty to implement a more visible way to outline region (like a line above the section opening).

Current state of my implementation is still what is visible in the animated gif in first post.

Surely need to solve a lot of conflicts now to get a mergable PR since more than one year has passed until my implementation.

[jmb462]

I've finally posted a PR taking into account comments done in this proposal.
Thanks for your interest.

godotengine/godot#74843

[seppoday]

PR looks dope AF. Love that feature.

[Calinou]

I wonder if we should mimic Swift/Xcode's // MARK syntax, which allows for optionally drawing a separator line above or below the mark.

That said, a // MARK has no concept of an "end", so it would likely be a separate special comment.

[drusepth]

That PR looks amazing and covers everything I was looking for above. Thanks for your work on this; this feature is standard in most IDEs and I'm glad to see it (hopefully) coming to Godot's, too.

[stryker313]

@jmb462 any chance this gets backported to 3.x?

[Calinou]

@jmb462 any chance this gets backported to 3.x?

This feature relies on a backwards-incompatible CodeEdit refactoring, so it would require recreating the feature from scratch. Given how complex the code is, I doubt that'll happen.