code style for Torque3D

[Johxz]

Hi

Well... the formatting of the source code is need it. The point of the post is:

- Can we start formatting the source code to be release to T3D v4?

- Will it interfere with your work? do not care?

- You want to propose other code style?

Torque3D seems to use Allman with 3 spaces

- https://en.wikipedia.org/wiki/Indent_style#Allman_style

more info here:

http://wiki.torque3d.org/coder:code-style-guidelines

http://tdn.garagegames.com/wiki/CodeStyleGuide

You can see some differences in here:

- https://gist.github.com/jesseschalken/0f47a2b5a738ced9c845

- https://en.wikipedia.org/wiki/Indent_style

Please vote:

- Yes or No?

- Code Style alternative?

write it down what you think....

PR: #2046

Edited July 15, 2017 by Johxz

[Duion]

I like K&R the most.

[Timmy]

I like the current Allman style, i have personally always used this even outside of T3D, i hate the K&R style with a passion lol. Just change to tabs instead of spaces and a tab size of 4, that's my vote.

[Duion]

You can setup notepad++ to exchange tabs with spaces, probably other coding programs as well, that will solve that.

[Timmy]

It's most likely a good idea to add support for http://editorconfig.org/ , there is support for all major editors/ide either natively or via a plugin. Github even supports it

[Bloodknight]

So, every couple years or so this topic pops up.

iirc the last one was literally all about the indents (i personally favour 4 over 2), the problem is that many developers have holy views regarding their style, and as such conversations generally end in religious debates on every single point.

Personally, i have a few pet hates, the first of which is un bracketed single conditionals, I can't tell you the number of times I've seen a conditional added to and then not work because braces weren't added; rookie mistake maybe, but relatively common none the less. My next pet hate is 2 space indents, I personally find the small indents problematic in that I can lose an indent when quick scanning the code, 4 space indents make it much more difficult to miss an indent.

Generally, I can work with whatever styles are being used, and adapt to that style when working on a specific project, lately, I've been tinkering with C# work and I've just left that shit as default because I can't be bothered to tinker with style settings.

The general consensus having discussed this with those who do most of the work was:-

1. Fix already not correctly styled code when working on those particular files.

2. A consensus is never likely to be reached within a wider audience.

There is another issue that needs to be mentioned, I have seen astyle and other similar systems completely break projects, so this is not as simple as just running a style fixer on a project. I suspect that trying this on torque, given some of the outright shitty and shifty practices that have gone on in the past would result in complete disaster and as such turning this exercise into a much larger task than necessary.

[Duion]

Ah what I forgot, I wanted to say that even though I prefer K&R style I would not suggest to change all code just because of that, that would just create a mess.

For smaller parts for example the templates and Torquescript this may be an option to change the style.

[Timmy]

There is another issue that needs to be mentioned, I have seen astyle and other similar systems completely break projects, so this is not as simple as just running a style fixer on a project. I suspect that trying this on torque, given some of the outright shitty and shifty practices that have gone on in the past would result in complete disaster and as such turning this exercise into a much larger task than necessary.

 

EditorConfig is not going to break Torque :?: .It's a suggestion to enforce rules, whatever those rules may be.

[Bloodknight]

@Timmy it was more of a tale of caution regards running a style changer across an entire codebase to get it up to scratch.

I do like the idea of a switchable style system that allows you to auto style for whichever project you are working on at the time, seems to be sadly lacking in IDEs

[Johxz]

thanks for the comments, this kind of fix does not break torque3D, I think is desperately need it, I know at some point in the past this was a topic and never landed, we can managed this kind of PR differently, I'm not going to do one PR with everything, I'm thinking of use smaller PR, this will help identify a problem If it's exist.

As some of you know t3d passed through by different collaborators, since many many years. I think we need to do it right now without waiting more. A lot of new people are waiting v4 to be released to start his project.

other of the benefit we can clearly see if someone new want to start collaborating to the code, instead teach him the Torque Code Style, you can simple point out to Allman or K&R for example, and avoid the always "3 spaces thing"

The http://editorconfig.org/ is a good idea I was thinking to implement something like this in the code itself like this http://kitware.github.io/KWStyle/, but this is not the point of this topic, remember we need to have a clearly code style first and apply it and avoid that a good PR hit the ground by something unclear and then we need to re-do it

we need the consent of the people that already started his project and want to upgrade later.

Edited July 16, 2017 by Johxz

[Duion]

Well there can be slight differences within coding styles, for example the preferred indend length, from 1 - 8 spaces/tabs everything exists.

Are the any inconsistencies in the code? I did not notice much.

And do automatic tools exist that can restyle the entire code automatically?

[Bloodknight]

yes, but they can break code, depending on what gets changed

[Timmy]

It's pretty trivial to correct anything if one of these automatic tools killed any code.

[Duion]

I did some more research into coding style and found K&R seems to be considered the best amongst experts, as it is used in the Linux kernel and many more big popular projects: https://www.kernel.org/doc/html/v4.10/process/coding-style.html also interesting to read the other style recommendations.

The main difference are the placement of the braces and the spaces, the Linux kernel uses 8 spaces for indentation and they argue that it enhances readability and that if you need more than 3 levels of indentation your code is bad anyway.

However Torque3D seems to use the Allman style variant which puts the opening braces all in their own lines and first I thought K&R was better, but now I see that Allman style enhances readability and the only disadvantage is using more lines, which is not that big of a problem.

I mean you could argue about some details like how many spaces to use, since 3 are less than the commonly used 4 or even 8 spaces per line, but as game code tends to have a lot of indentations often, 3 lines is a fine choice, so the code does not move too far to the right and 2 spaces would be too little for a significant visual separation.

There seem to be some inconsistencies in the Torque code since .gui and .mis files use a different brace style having the opening brace at the end of the first line instead of using a separate line for them, no idea what the intend behind this is, but as those files are mostly autogenerated from the engine and hardly edited by hand and only a list of items, it would not add much benefit changing it anyway.

So I tend to agree to the way it already is now and suggest not to change Torque3D coding style at all.