Update code style to match what's actually used

[samdark]

https://github.com/yiisoft/yii2/wiki/Core-framework-code-style

[qiangxue]

should also summarize the API documentation styles, especially about the usage of markdown tags (this is still a work-in-progress).

[navarr]

This might be the wrong place for this - but why not the PHP-Fig Recommendation Standards?

[resurtm]

@navarr, it's already used with some minor changes. Btw, PSR-×'s are not the ultimate truth—it's called Proposing a Standards Recommendation after all.

[rawtaz]

PHP-Fig sure as hell is not a magic bullet on the topic of code style standards. Personally I think there's a lot of things in it that is utter nonsense. It doesn't matter how much they consider this a standard, there will always be at least two camps on every piece of style in it. Do what makes sense, not what some lousy standards attempt states :)

[klimov-paul]

I consider PSR-2 is one of the best code style proposals.
The main goal of the code style is making the source code readable and minimize possible typo errors.
Such goals are achived by requiring extra spaces aroung some contructions and some rules like "any case in switch operator, which does not invoke break, should have comment 'no break'".

There is only one thing, which I dislike at PSR-2: it recommends to place open brackets ("{") for classes and the functions at the next line after thier definition. At my opinion it simply wastes an extra row.

[sensorario]

Yii2 can have it's own coding standard ... https://github.com/squizlabs/PHP_CodeSniffer/tree/master/CodeSniffer/Standards

[klimov-paul]

It has. Yii2 code style does not completely match PSR-2, while it is based on it.

[samdark]

Extended style description https://github.com/yiisoft/yii2/wiki/Core-framework-code-style

[klimov-paul]

Question 1: Why we are using tabs instead of spaces for indention?

There are 2 common approaches for the code block indention: using tabs or using 4 spaces.
Not so long ago almost all coding standards declared the spaces should be used. The main reason for such requirement was a problem for the “diff” programs to recognize and handle tabs properly.
I am not sure such problem exists nowadays. However I personally prefer spaces indention for other reason. Tabs may be displayed differently depending on the text editor you are using. Most IDE shows tab character as 4 spaces by default, however most OS standard text editors (“notepad” for Windows, “vi” and “vim” for Linux) show them as 8 spaces. Also there are programs, which show tabs as 2 spaces. I am not always able to use IDE during the project development: sometimes I need to quick check something at the remote server and use good old “vi” or “vim” for it. When I do so I am feeling not comfortable, while the code formatting looks rather different from the one I get used to in IDE.
Also there is a problem in the team programming. Sometimes I need to perform dual programming or consulting for another developer at his work machine. If I use code style, which dictates using of “tabs”, I can have the same discomfort as at “vim”. Once I have a arguing with developer, who setup his IDE displaying tabs as 2 spaces long. I have tried to say him the code becomes unreadable this way, but he says “the code style is applied, stop bother me”.

I prefer 4 spaces, because spaces are always spaces no matter which program do you use to browse code, while tabs appearance may vary.

[qiangxue]

Modern editors (even vi/vim, just do :set tabstop=4) should be able to configure how many spaces a tab represents. This gives you the freedom of choosing your favorite indention size. If you use spaces, you don't have this freedom. Moreover, when you want to move the cursor in a line, moving through tabs takes less typings than spaces.

Let's not bring up the war between tabs and spaces again. The more important thing is we should be consistent. And this coding style only applies to the Yii core code.

[klimov-paul]

Question #2: Why place open bracket for classes and functions at the new line?

While studying at the academy, I have learned several program languages. Pascal, C++, Java were among them. All these languages use special constructions for the code blocks: “begin/end” at Pascal, “{}” at C++ and Java.
When I read the code samples on Pascal the “begin” keyword was always placed at the new line:

procedure myProc()
begin
    /* some code here */
end;

When I read code samples on C++, the open brackets were placed in different positions:

void function myFunc(int a)
{
    if (a>10) {
        // some code
    } else {
        // else code
    }
}

Why C++ place open bracket at the same line as the control structure begins? – Because it can. In Pascal placing “begin” keyword at the same line with the control structure will make code hard to read, because Pascal is too verbose:

if (a>10) then begin
    /* some code here */
end;

In opposite placing open brackets at the new line in C++ will make its code to be stretched without purpose:

if (a>10)
{
    // this seems empty
}
else
{
    // really empty
}

The first time I ever heard about coding standards was when I was studying Java. Java code standard dictates the open brackets for the code block always should be at the same line as it parent control structure:

int function myFunc(int a) {
    if (a>10) {
        // some code
    } else {
        // else code
    }
}

For the long time I considered Java code style as best for all “C”-like program languages. I was surprised when I come across PSR-2 standard for PHP, which tells open brackets should be placed at the same like for operators like “if” or “for”, but at the next line for class or function definition.
Why?
Why should I place the same code statement in different styles depending on what exactly control structure is? Don’t I have a better thing to keep in mind than such branching?

I have digged around this a bit and found out, why such unlogical rule has appeared. The “C” programming language is very old and it was changed a lot during its lifetime. When the first “C” code style has been created it was dictating the open brackets for code blocks should be placed at the same line with the control structures, no matter what this structure is. However at that time the function definition was rather different from the one we all used to:

function myFunc
    int x,
    int y;
{
    // function code
}

It was necessary to place each function argument at the new line, at there was no option to place the open bracket at the same line with the function definition. That is why the first “C” code style tells for functions open brackets should be placed at the new line.
Long after that the syntax of “C” has been changed, and function definition became:

function myFunc(int x, int y) 
{
    // function code
}

Using new line for the function brackets is just a legacy of the old “C” syntax and has no practical usage, it just throws a line of code away.
Compare:

function myFunc($x, $y) 
{
    if ($x==$y) {
        echo ‘x equals to y’;
    } else {
        echo ‘x not equals to y’;
    }
}

and

function myFunc($x, $y) {
    if ($x==$y) {
        echo ‘x equals to y’;
    } else {
        echo ‘x not equals to y’;
    }
}

My Academy Java instructor always told: only amateur, who can not forget Pascal, place the open brackets at new line.

[navarr]

We're very literally arguing semantics here.

My reason for bringing up PSR-2 was because it is (a) recognized by IDEs (except perhaps Eclipse, unless you know what you're doing) and (b) Is already programmed into many code quality testing tools, and democratically accepted by the larger PHP community as a standard for the most optimum amount of interoperability.

The intent was not to start this very large list of things you're keen on saying, @klimov-paul.

And while this is definitely not the right place for this, it is a very big shame that Yii does not have a representative in the PHP-FIG.

[klimov-paul]

[qiangxue]

@klimov-paul I had the similar doubt about the inconsistency about the bracket location in the first style which is adopted by most PHP projects. Over the time, I convinced myself to take it for this reason: a class or a function is a like an article or a chapter which needs a title on a single line by its own. While statements within a function are like sentences which if having brackets on separate lines would appear too empty.