пятница, мая 30, 2008

Хороший стиль 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, который мы сейчас и разберем.

4 комментария:

dimpiax комментирует...

Уж очень много спорных моментов.

Racer комментирует...

Много. Но много полезных правил. Я уже многое успешно пользую - помогает.

Alek83 комментирует...

Я пришел к Flex из Java и считаю Java-стайл самым читабельным :)

Многое похоже, но низачто меня не заставить переносить фигурные скобки на следующую строку.. да и зачем? лишняя строка кода.. читабельности ни добавляется ни грамма

Racer комментирует...

Это просто дело привычки.
Интересно а ктонть пользует смешанный стиль? Я никак не могу совсем перейти на перенос скобки, и у меня только в функциях есть перенос, а в операторах - нет :).