Хороший стиль Flex-программирования. Форматирование

Здесь речь пойдет о том, как лучше оформлять файлы Flex-фреймворка. Статья Formatting.

Форматирование

Длина строки

Используйте перенос на следующую строку, если длина строки превышает 80 символов. Это дает следующие преимущества:

• Разработчикам, у которых экран имеет малое разрешение, не потребуется горизонтально прокручивать длинные строки текста.
• Можно комфортно сравнивать две версии программного кода, расположив два окна встык.
• При показе кода на экране проектора, можно установить большой размер шрифта, и при этом не потребуется горизонтально прокручивать текст.
• При печати, исходный код не будет обрезаться, или непредсказуемо переноситься.

Отступы

Используйте отступы в 4 пробела. Настройте редактор так, чтобы вместо символа табуляции вставлялись символы пробелов. Это необходимо для того, чтобы в код выглядел без искажений в программах с другой системой формирования отступов. Например Notepad отображает отступы в 8 символов.

Разделительные блоки

Код необходимо разбивать на разделы, а полученные разделы - озаглавливать. Для этого используйте большой и малый разделители.

Большой разделитель выглядит следующим образом:

//--------------------------------------------------------------------------
//
// Overridden methods
//
//--------------------------------------------------------------------------

Блок большого разделителя начинается с 4-го символа строки и заканчивается на 80-м. Текст начинается с 8-го символа.

Малый разделитель выглядит следующим образом:

//----------------------------------
// visible
//----------------------------------

Блок малого разделителя начинается с 4-го символа строки и заканчивается на 40-м. Текст начинается с 8-го символа.

Необходимо вставлять одну пустую строку до и одну после каждого разделителя.

Разделение блоков объявления

Используйте одну пустую строку для разделения блоков объявления констант, переменных, функций:
/**
* @private
* Holds something.
*/
var a:Number;
/**
* @private
*/
var b:Number


Метаданные

можно: Inspectable[a="1", b="2"]
нельзя: Inspectable[a=1 b=2]

Индексирование массивов

Не ставьте пробелы:
- до или после левой квадратной скобки,
- перед правой квадратной скобкой.

можно: a[0]
нельзя: a [ 0 ]

Расстановка запятых

После запятой, оставляйте один пробел. Это правило распространяется на список аргументов, элементы массива, свойства объекта.

Массивы

Ставьте один пробел:
- после левой квадратной скобки,
- перед правой квадратной скобкой,
- после каждой запятой.

можно: [ 1, 2, 3 ]
нельзя: [1, 2, 3] [1,2,3]

Исключение составляет только пустой массив:
можно: []
нельзя: [ ]

Если строка инициализации массива слишком длинна, разбивайте ее на несколько строк с выравниванием квадратных скобок:

static var numberNames:Array /* of String */ =
[
     "zero",
    "one",
    "two",
    "three",
    "four",
    "five",
    "six",
    "seven",
    "eight",
    "nine"
];

Объекты

Ставьте один пробел:
- после левой фигурной скобки,
- перед правой фигурной скобкой,
- после каждого двоеточия,
- после каждой запятой.

можно: { a: 1, b: 2, c: 3 }
нельзя: {a: 1, b: 2, c: 3} {a:1, b:2, c:3} {a:1,b:2,c:3}

Исключение составляет только пустой массив:
можно: {}
нельзя: { }

Если строка инициализации объекта слишком длинна, разбивайте ее на несколько строк с выравниванием квадратных скобок:

private static var TextStyleMap:Object =
{
    color: true,
    fontFamily: true,
    fontSize: true,
    fontStyle: true,
    fontWeight: true,
    leading: true,
    marginLeft: true,
    marginRight: true,
    textAlign: true,
    textDecoration: true,
    textIndent: true
};

Функции

Пример форматирования:

var f:Function;
f = function():void
{
    doSomething();
};

Объявление типов

Не ставьте пробелы до и после двоеточия, которое разделяет имя переменной, параметра, или функцию от типа.

можно: var n:Number;
нельзя:
var n : Number;
var n: Number;

можно: function f(n:Number):void
нельзя:
function f(n : Number) : void
function f(n: Number): void

Использование пробелов в операторах

Ставьте пробелы до и после оператора присваивания:
можно: a = 1;
нельзя: a=1;

Ставьте пробелы до и после инфиксного оператора:
можно: a + b * c
нельзя: a+b*c

Ставьте пробелы до и после оператора сравнения:
можно: a == b
нельзя: a==b

Не ставьте пробел между префиксным оператором и операндом:
можно: !o
нельзя: ! o

Не ставьте пробел между операндом и постфиксным оператором:
можно: i++
нельзя: i ++

Операторы

Начинайте каждый оператор с новой строки. Это дает возможность установить контрольную точку (breakpoint) на любой из операторов.
можно:
a = 1;
b = 2;
c = 3;
нельзя:
a = 1; b = 2; c = 3;

Всегда выравнивайте фигурные скобки блоков операторов:
можно:

function f():void
{
    var n:int = numChildren;
    for (var i:int = 0; i < n; i++)
    {
        if ()
        {
            x = horizontalGap * i;
            y = verticalGap * i;
        }
    }
}

Нельзя:

function f():void {
    var n:int = numChildren;
    for (var i:int = 0; i < n; i++) {
        if () {
            x = horizontalGap * i;
            y = verticalGap * i;
        }
    }
}

Объявление функций

Ставьте один пробел после каждой запятой. Никогда не ставьте пробелов после левой скобки и перед правой скобкой:
можно: f(a, b)
нельзя: f(a,b) f( a, b )

Если список параметров переносится на другую строку, перенесенные строки должны иметь отступ на уровне первого параметра после левой скобки. Можно располагать несколько параметров на одной строке, только если они умещаются. В ином случае, располагайте каждый параметр на отдельной строке. Если четный параметр не умещается, перенесите первый параметр на следующую строку с отступом на уровне начала имени функции.

public function foo(parameter1:Number, parameter2:String,
                    parameter3:Boolean):void

public function foo(parameter1:Number,
                    parameter2:String,
                    parameter3:Boolean):void

public function aVeryLongFunctionName(
                parameter1:Number, parameter2:String,
                parameter3:Boolean):void

Вызов функций

Ставьте один пробел после каждой запятой. Никогда не ставьте пробелов после левой скобки и перед правой скобкой:
можно: f(a, b)
нельзя: f(a,b) f( a, b )

Оператор if

Ставьте пробел между ключевым словом if и левой скобкой. Никогда не ставьте пробелов после левой скобки и перед правой скобкой:
можно: if (a < b)
нельзя:
if(a < b)
if( a < b )
if ( a < b )

Оператор for

Ставьте пробел между ключевым словом for и левой скобкой. Никогда не ставьте пробелов после левой скобки и перед правой скобкой:
можно: for (var i:int = 0; i < n; i++)
нельзя:
for(var i:int = 0; i < n; i++)
for( var i:int = 0; i < n; i++ )
for ( var i:int = 0; i < n; i++ )

Если описание цикла переносится на другую строку, перенесенные строки должны иметь отступ на уровне первого символа после левой скобки:

for (var aLongLoopVariableName:int = aLongInitialExpression;
     aLongLoopVariableName < aLongUpperLimit;
     aLongLoopVariableName++)

Оператор switch

Ставьте пробел между ключевым словом switch и левой скобкой. Никогда не ставьте пробелов после левой скобки и перед правой скобкой:
можно: switch (n)
нельзя:
switch(n)
switch( n )
switch ( n )

Комментарий

По всей видимости исходная статья находится на стадии разработки, т.к. под конец вылезло множество ошибок и обрывков фраз. Сделаю ревизию через пару месяцев.

В основном, всё логично и выполнимо. Последний FlashDevelop успешно реализует эти правила в своем автокомплите. Теперь стало ясно, почему они так резко изменили политику расстановки фигурных скобок функций, а именно, перенос левой фигурной скобки на следующую строку. Честно говоря, я с этим переносом намучался, поскольку при переходе на стиль форматирования FlashDevelop, я специально переучивался оставлять левую скобку на строке с определением функции. А тут вдруг огорошили... И опять возвращаться к прежнему формату.

Ну всё. Следующий проект начинаю правильно форматировать.

Кстати, о проектах, которые сделаны в старом (не по правилам) формате. Часто приходится к ним возвращаться, дорабатывать, улучшать. Но уже трудно работать по-старому. Как тут быть? На переформатирование времени тратить не хочется. Где взять такой реформатер??!

Пока для себя я держу правило - работать в контексте стиля программирования дорабатываемого кода. Мой это код или чужой - всё равно следовать правилам текущего документа.
Если проект важный, в итоге будет выделено время на рефакторинг и всё само собой встанет на места.
Если проект чужой - он, вероятно, попадет обратно к автору, а тот лучше поймет что ему делать со своими или не своими (но похожими :) ) каракулями.

Остался маленький "хвостик" про ASDoc, который мы сейчас и разберем.