Terasology Code Style Conventions

[Immortius]

I don't think so, I guess it is there for reference?

 

[Cervator]

I don't think so, I guess it is there for reference?

Maybe. mkalb ?

 

[mkalb]

Cervator : The file "sun_checks.xml" exists only for reference.

Please, can someone define the maximum line length. (@Immortius, begla, Cervator)

I want to use it for the TerasologyLauncher (Checkstyle and IDEA code format).

I started to develop with IDEA because it is not possible to define the same style and formating rules with Eclipse.

I installed IntelliJIDEA 12 and changed the settings for the imports. Which other style/format rules should I change?

 

[Cervator]

Based on my earlier comments I'd say between 120-140, I have little preference to the exact number in that range

Anybody object?

mkalb - feel free to pick a number in that range and add the config. Other than the import style I'm not sure if there are any base IntelliJ tweaks to make. Other than maybe 4 spaces for tabs if that isn't a default already.

Speaking of, do we have a style capturing tabs instead of spaces? I've forgotten (and am at work)

 

[Immortius]

Go with 120.

 

[mkalb]

I installed a fresh new version of IntelliJIDEA 12 and changed the following settings.

 

[synopia]

I would suggest to remove the name hiding check from checkstyle.

Otherwise, following code is not allowed:

class Foo {
  private int xyz;
  public Foo( int xyz ) {
    this.xyz = xyz;
  }
}

Maybe there is an option, to only allow name hiding in constructors.

 

[Immortius]

The rule doesn't apply to constructors, at least in my environment?

 

[mkalb]

Yes, constrcutor and setter normaly don't create warnings.

 

[msteiger]

The first post mentions that Java6 is the target version. Is this still the case?

Btw: is there a condensed version (maybe a Wiki page) of all code conventions and in how they differ from the original Sun styling?
eclipse has a nice example code snippet that shows all currently applied formatting rules. This makes it easy to see all rules in one view ..

 

[mkalb]

Java 7 is the new target version

 

[Cervator]

Edited a quick Java 7 note into the first post

A wiki page with the convention and a quick example for each sounds like a great idea. Once more unto the todo list, dear friends, once more!

 

[msteiger]

I can do that tonight, I just need a few things:

• Someone who knows TS code well enough to verify / change stuff as needed
• Someone who has write access to the wiki (which wiki anyway?)
• Wiki format language (the forums wiki-language or github markdown ?)

 

[Cervator]

Wiki: https://github.com/MovingBlocks/Terasology/wiki so GitHub markdown

I think write access is pretty widely available. I just added you and Josharias to the official Contributor group on GitHub so you should be able to create a new page and edit it all in yourself. I'll be happy to do a review - that's a lot easier than the initial write-up with limited time availability. Immortius probably would be up for that too sometime

 

[msteiger]

The Wiki page can be found here: https://github.com/MovingBlocks/Terasology/wiki/Coding-Conventions
There's also an "under-construction" disclaimer at the top.
It should be removed as soon as the core devs agreed on a final version.

 

[Immortius]

The Sun Standard and Maven standard directory layout should still be the initial goto for Terasology's style.

 

[manu3d]

I'm finding the use of

//<editor-fold desc="Section Name">
...
// </editor-fold>

blocks quite useful to make long(ish) heterogeneous classes more readable. I.e. attached is a screenshot of how TerasologyEngine.java looks like after a bit of reorganizing to better understand it. Is this any useful? Allowed? Frowned upon? Are there other, preferred ways to divide a file into logical sections of more tightly related parts?

 

[Cervator]

Is that specific to IntelliJ though ? That might be the biggest issue in adding these sorts of meta-tags - unless there is a type supported across all three major IDEs, or maybe even more editors.

It is a cool thought, but not sure how viable

 

[Immortius]

I know I've had this discussion before with someone, but no idea where.

Basic conclusion was no code folding - see http://blog.codinghorror.com/the-problem-with-code-folding/ for some reasons. Essentially it bloats code, and hides code smells - if you have 6 different sections of methods that handle 6 different things, perhaps you should actually have 6 classes? If you can only make sense of them within a named region, perhaps the method names need improvement?

Additionally, there's no common standard in Java for code fold structure, so we cannot maintain cross-IDE support.

IntelliJ already supports a fair bit of code folding for methods, blocks, anonymous inner classes and one line methods. I think we should stick with that.

 

[msteiger]

Afaik, eclipse doesn't support the editor-fold tag - at least not out-of-the-box. There's support for code folding of methods, classes and comment sections, though.
I would go for more javadoc and fold it in the IDE where appropriate.