406 lines
21 KiB
Markdown
406 lines
21 KiB
Markdown
# Советы по стилю кода
|
||
|
||
Код должен быть максимально читаемым и понятным. Для этого нужен *хороший стиль* написания кода. В этой главе мы рассмотрим компоненты такого стиля.
|
||
|
||
[cut]
|
||
## Синтаксис
|
||
|
||
Шпаргалка с правилами синтаксиса:
|
||
|
||
<img src="cheatsheet.png">
|
||
|
||
Разберём основные моменты.
|
||
|
||
### Фигурные скобки
|
||
|
||
Пишутся на той же строке, так называемый "египетский" стиль. Перед скобкой -- пробел.
|
||
|
||
<img src="figure.png">
|
||
|
||
Если у вас уже есть опыт в разработке и вы привыкли делать скобку на отдельной строке -- это тоже вариант. В конце концов, решать вам. Но в основных JavaScript-фреймворках (jQuery, Dojo, Google Closure Library, Mootools, Ext.JS, YUI...) стиль именно такой.
|
||
|
||
Если условие и код достаточно короткие, например `if (cond) return null;`, то запись в одну строку вполне читаема... Но, как правило, отдельная строка всё равно воспринимается лучше.
|
||
|
||
### Длина строки
|
||
|
||
Максимальную длину строки согласовывают в команде. Как правило, это либо `80`, либо `120` символов, в зависимости от того, какие мониторы у разработчиков.
|
||
|
||
Более длинные строки необходимо разбивать. Если этого не сделать, то перевод очень длинной строки сделает редактор, и это может быть менее красиво и читаемо.
|
||
|
||
### Отступы
|
||
|
||
Отступы нужны двух типов:
|
||
|
||
<ul>
|
||
<li>**Горизонтальный отступ, при вложенности -- два(или четыре) пробела.**
|
||
|
||
Как правило, используются именно пробелы, т.к. они позволяют сделать более гибкие "конфигурации отступов", чем символ "Tab".
|
||
|
||
Например:
|
||
|
||
```js
|
||
function fib(n) {
|
||
*!*
|
||
var a = 1;
|
||
var b = 1;
|
||
*/!*
|
||
for (var i = 3; i <= n; i++) {
|
||
var c = a + b;
|
||
a = b;
|
||
b = c;
|
||
}
|
||
return b;
|
||
}
|
||
```
|
||
|
||
Кстати, обратите внимание, переменные в выделенном фрагменте объявлены по вертикали, а не в строку `var a=1, b=1`. Так более наглядно, человеческий глаз лучше воспринимает ("сканирует") вертикально выравненную информацию, нежели по горизонтали. Это известный факт среди дизайнеров и нам, программистам, он тоже будет полезен для лучшей организации кода.
|
||
|
||
</li>
|
||
<li>**Вертикальный отступ, для лучшей разбивки кода -- перевод строки.**
|
||
|
||
Используется, чтобы разделить логические блоки внутри одной функции. В примере ниже разделены функция `pow`, получение данных `x,n` и их обработка `if`.
|
||
|
||
```js
|
||
function pow(x, n) {
|
||
return (n != 1) ? pow(x, n-1) : x;
|
||
}
|
||
// <--
|
||
x = prompt(...);
|
||
n = prompt(...);
|
||
// <--
|
||
if (n >= 1) {
|
||
var result = pow(x, n);
|
||
alert(result);
|
||
}
|
||
```
|
||
|
||
Вставляйте дополнительный перевод строки туда, где это сделает код более читаемым. Не должно быть более 9 строк кода подряд без вертикального отступа.
|
||
</li>
|
||
</ul>
|
||
|
||
### Точка с запятой
|
||
|
||
Точки с запятой нужно ставить, даже если их, казалось бы, можно пропустить.
|
||
|
||
Есть языки, в которых точка с запятой не обязательна, и её там никто не ставит. В JavaScript она тоже не обязательна, но ставить нужно. В чём же разница?
|
||
|
||
Она в том, что **в JavaScript без точки с запятой возможны трудноуловимые ошибки.** С некоторыми примерами вы встретитесь дальше в учебнике. Такая вот особенность синтаксиса. И поэтому рекомендуется её всегда ставить.
|
||
|
||
## Именование
|
||
|
||
Общее правило:
|
||
<ul>
|
||
<li>Имя переменной -- существительное.</li>
|
||
<li>Имя функции -- глагол или начинается с глагола. Бывает, что имена для краткости делают существительными, но глаголы понятнее.</li>
|
||
</ul>
|
||
|
||
Для имён используется английский язык (не транслит) и верблюжья нотация.
|
||
|
||
Более подробно -- читайте про [имена функций](#function-naming) и [имена переменных](#variable-naming).
|
||
|
||
## Уровни вложенности
|
||
|
||
**Уровней вложенности должно быть немного.**
|
||
|
||
Например, [проверки в циклах лучше делать через "continue"](#continue), чтобы не было дополнительного уровня `if(..) { ... }`:
|
||
|
||
Вместо:
|
||
|
||
```js
|
||
for (var i=0; i<10; i++) {
|
||
if (i подходит) {
|
||
... // <- уровень вложенности 2
|
||
}
|
||
}
|
||
```
|
||
|
||
Используйте:
|
||
|
||
```js
|
||
for (var i=0; i<10; i++) {
|
||
if (i *!*не*/!* подходит) *!*continue*/!*;
|
||
... // <- уровень вложенности 1
|
||
}
|
||
```
|
||
|
||
Аналогичная ситуация -- с `if/else` и `return`. Следующие две конструкции идентичны.
|
||
|
||
Первая:
|
||
|
||
```js
|
||
function isEven(n) { // проверка чётности
|
||
if (n % 2 == 0) {
|
||
return true;
|
||
*!*
|
||
} else {
|
||
return false;
|
||
}
|
||
*/!*
|
||
}
|
||
```
|
||
|
||
Вторая:
|
||
|
||
```js
|
||
function isEven(n) { // проверка чётности
|
||
if (n % 2 == 0) {
|
||
return true;
|
||
}
|
||
|
||
*!*
|
||
return false;
|
||
*/!*
|
||
}
|
||
```
|
||
|
||
Если в блоке `if` идёт `return`, то `else` за ним не нужен.
|
||
|
||
**Лучше быстро обработать простые случаи, вернуть результат, а дальше разбираться со сложным, без дополнительного уровня вложенности.**
|
||
|
||
В случае с функцией `isEven` можно было бы поступить и проще:
|
||
|
||
```js
|
||
function isEven(n) { // проверка чётности
|
||
return n % 2 == 0;
|
||
}
|
||
```
|
||
|
||
..Казалось бы, можно пойти дальше, есть ещё более короткий вариант:
|
||
|
||
```js
|
||
function isEven(n) { // проверка чётности
|
||
return !(n % 2);
|
||
}
|
||
```
|
||
|
||
...Однако, код `!(n % 2)` менее очевиден чем `n % 2 == 0`. Поэтому, на самом деле, последний вариант хуже. **Главное для нас -- не краткость кода, а его простота и читаемость.**
|
||
|
||
## Функции = Комментарии
|
||
|
||
**Функции должны быть небольшими.** Если функция большая -- желательно разбить её на несколько.
|
||
|
||
Этому правилу бывает сложно следовать, но оно стоит того. При чем же здесь комментарии?
|
||
|
||
Вызов отдельной небольшой функции не только легче отлаживать и тестировать -- сам факт его наличия является *отличным комментарием*.
|
||
|
||
Сравните, например, две функции `showPrimes(n)` для вывода простых чисел до `n`.
|
||
|
||
Первый вариант:
|
||
|
||
```js
|
||
function showPrimes(n) {
|
||
nextPrime:
|
||
for (var i=2; i<n; i++) {
|
||
|
||
for (var j=2; j<i; j++) {
|
||
if ( i % j == 0) continue nextPrime;
|
||
}
|
||
|
||
alert(i); // простое
|
||
}
|
||
}
|
||
```
|
||
|
||
Второй вариант, вынесена подфункция `isPrime(n)` для проверки на простоту:
|
||
|
||
```js
|
||
function showPrimes(n) {
|
||
|
||
for (var i=2; i<n; i++) {
|
||
*!*if (!isPrime(i)) continue;*/!*
|
||
|
||
alert(i); // простое
|
||
}
|
||
}
|
||
|
||
function isPrime(n) {
|
||
for (var i=2; i<n; i++) {
|
||
if ( n % i == 0) return false;
|
||
}
|
||
return true;
|
||
}
|
||
```
|
||
|
||
Второй вариант проще и понятнее, не правда ли? Вместо участка кода мы видим описание действия, которое там совершается (проверка `isPrime`).
|
||
|
||
## Функции -- под кодом
|
||
|
||
Есть два способа расположить функции, необходимые для выполнения кода.
|
||
|
||
<ol>
|
||
<li>Функции над кодом, который их использует:
|
||
|
||
```js
|
||
// *!*объявить функции*/!*
|
||
function createElement() {
|
||
...
|
||
}
|
||
|
||
function setHandler(elem) {
|
||
...
|
||
}
|
||
|
||
function walkAround() {
|
||
...
|
||
}
|
||
|
||
// *!*код, использующий функции*/!*
|
||
var elem = createElement();
|
||
setHandler(elem);
|
||
walkAround();
|
||
```
|
||
|
||
</li>
|
||
<li>Сначала код, а функции внизу:
|
||
|
||
```js
|
||
// *!*код, использующий функции*/!*
|
||
var elem = createElement();
|
||
setHandler(elem);
|
||
walkAround();
|
||
|
||
// --- *!*функции*/!* ---
|
||
|
||
function createElement() {
|
||
...
|
||
}
|
||
|
||
function setHandler(elem) {
|
||
...
|
||
}
|
||
|
||
function walkAround() {
|
||
...
|
||
}
|
||
```
|
||
|
||
</li>
|
||
</ol>
|
||
|
||
...На самом деле существует еще третий "стиль", при котором функции хаотично разбросаны по коду ;), но это ведь не наш метод, да?
|
||
|
||
**Как правило, лучше располагать функции под кодом, который их использует.** То есть, это 2й способ.
|
||
|
||
Дело в том, что при чтении такого кода мы хотим знать в первую очередь, *что он делает*, а уже затем *какие функции ему помогают.* Если первым идёт код, то это как раз дает необходимую информацию. Что же касается функций, то вполне возможно нам и не понадобится их читать, особенно если они названы адекватно и то, что они делают, понятно.
|
||
|
||
У первого способа, впрочем, есть то преимущество, что на момент чтения мы уже знаем, какие функции существуют.
|
||
|
||
Таким образом, если над названиями функций никто не думает -- может быть, это будет лучшим выбором :). Попробуйте оба варианта, но по моей практике предпочтителен всё же второй.
|
||
|
||
|
||
## Комментарии
|
||
|
||
В коде нужны комментарии.
|
||
|
||
**Как правило, комментарии отвечают на вопрос "что происходит в коде?"**
|
||
|
||
Например:
|
||
<ul>
|
||
<li>**Архитектурный комментарий -- "как оно, вообще, устроено".**
|
||
|
||
Какие компоненты есть, какие технологии использованы, поток взаимодействия. О чём и зачем этот скрипт. Эти комментарии особенно нужны, если вы не один.
|
||
|
||
Для описания архитектуры, кстати, создан специальный язык [UML](http://ru.wikipedia.org/wiki/Unified_Modeling_Language), красивые диаграммы, но можно и без этого. Главное -- чтобы понятно.
|
||
</li>
|
||
<li>**Справочный комментарий перед функцией -- о том, что именно она делает, какие параметры принимает и что возвращает.**
|
||
|
||
Для таких комментариев существует синтаксис [JSDoc](http://en.wikipedia.org/wiki/JSDoc).
|
||
|
||
```js
|
||
/**
|
||
* Возвращает x в степени n, только для натуральных n
|
||
*
|
||
* @param {number} x Число для возведения в степень.
|
||
* @param {number} n Показатель степени, натуральное число.
|
||
* @return {number} x в степени n.
|
||
*/
|
||
function pow(x, n) {
|
||
...
|
||
}
|
||
```
|
||
|
||
Такие комментарии позволяют сразу понять, что принимает и что делает функция, не вникая в код.
|
||
|
||
Кстати, они автоматически обрабатываются многими редакторами, например [Aptana](http://aptana.com) и редакторами от [JetBrains](http://www.jetbrains.com/), которые учитывают их при автодополнении.
|
||
</li>
|
||
<li>**Краткий комментарий, что именно происходит в данном блоке кода.**
|
||
|
||
Что интересно, в коде начинающих разработчиков обычно комментариев либо нет, либо они как раз такого типа: "что делается в этих строках кода".
|
||
|
||
На самом деле именно эти комментарии, как правило, являются самыми ненужными. Хороший код и так самоочевиден, если не используются особо сложные алгоритмы.
|
||
|
||
Об этом замечательно выразился Р. Мартин в книге ["Чистый код"](http://www.ozon.ru/context/detail/id/21916535/): "Если вам кажется, что нужно добавить комментарий для улучшения понимания, это значит, что ваш код не достаточно прост, и, может, стоит переписать его".
|
||
|
||
</li>
|
||
</ul>
|
||
|
||
**...Но куда более важными могут быть комментарии, которые объясняют не *что*, а *почему* в коде происходит именно это!**
|
||
|
||
Как правило, из кода можно понять, что он делает. Бывает, конечно, всякое, но, в конце концов, вы этот код *видите*. Однако гораздо важнее может быть то, чего вы *не видите*!
|
||
|
||
*Почему* это сделано именно так? На это сам код ответа не даёт.
|
||
|
||
Например:
|
||
|
||
<ul>
|
||
<li>**Есть несколько способов решения задачи. Почему выбран именно этот?**
|
||
|
||
Например, пробовали решить задачу по-другому, но не получилось -- напишите об этом. Почему вы выбрали именно этот способ решения? Особенно это важно в тех случаях, когда используется не первый приходящий в голову способ, а какой-то другой.
|
||
|
||
Без этого возможна, например, такая ситуация:
|
||
<ul>
|
||
<li>Вы открываете код, который был написан какое-то время назад, и видите, что он "неоптимален".</li>
|
||
<li>Думаете: "Какой я был дурак", и переписываете под "более очевидный и правильный" вариант.</li>
|
||
<li>...Порыв, конечно, хороший, да только этот вариант вы уже обдумали раньше. И отказались, а почему -- забыли. В процессе переписывания вспомнили, конечно (к счастью), но результат - потеря времени на повторное обдумывание.</li>
|
||
</ul>
|
||
|
||
Комментарии, которые объясняют поведение кода, очень важны. Они помогают понять происходящее и принять правильное решение о развитии кода.
|
||
|
||
</li>
|
||
<li>**Какие неочевидные возможности обеспечивает этот код?** Где в другом месте кода они используются?
|
||
|
||
В хорошем коде должно быть минимум неочевидного. Но там, где это есть -- пожалуйста, комментируйте.
|
||
</li>
|
||
|
||
</ul>
|
||
|
||
Один из показателей хорошего разработчика -- качество комментариев, которые позволяют эффективно поддерживать код, возвращаться к нему после любой паузы и легко вносить изменения.
|
||
|
||
|
||
## Руководства по стилю
|
||
|
||
Когда написанием проекта занимается целая команда, то должен существовать один стандарт кода, описывающий где и когда ставить пробелы, запятые, переносы строк и т.п.
|
||
|
||
Сейчас, когда есть столько готовых проектов, нет смысла придумывать целиком своё руководство по стилю. Можно взять уже готовое, и которому, по желанию, всегда можно что-то добавить.
|
||
|
||
Большинство есть на английском, сообщите мне, если найдёте хороший перевод:
|
||
|
||
<ul>
|
||
<li>[Google JavaScript Style Guide](http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml)</li>
|
||
<li>[JQuery Core Style Guidelines](http://docs.jquery.com/JQuery_Core_Style_Guidelines)</li>
|
||
<li>[Idiomatic.JS](https://github.com/rwldrn/idiomatic.js) (есть [перевод](https://github.com/rwldrn/idiomatic.js/tree/master/translations/ru_RU))</li>
|
||
<li>[Dojo Style Guide](http://dojotoolkit.org/community/styleGuide)</li>
|
||
</ul>
|
||
|
||
Для того, чтобы начать разработку, вполне хватит элементов стилей, обозначенных в этой главе. В дальнейшем, посмотрите на эти руководства, найдите "свой" стиль ;)
|
||
|
||
### Автоматизированные средства проверки
|
||
|
||
Существуют онлайн-сервисы, проверяющие стиль кода.
|
||
|
||
Самые известные -- это:
|
||
|
||
<ul>
|
||
<li>[JSLint](http://www.jslint.com/) -- проверяет код на соответствие [стилю JSLint](http://www.jslint.com/lint.html), в онлайн-интерфейсе вверху можно ввести код, а внизу различные настройки проверки, чтобы сделать её более мягкой. </li>
|
||
<li>[JSHint](http://www.jshint.com/) -- ещё один вариант JSLint, ослабляющий требования в ряде мест.</li>
|
||
<li>[Closure Linter](https://developers.google.com/closure/utilities/) -- проверка на соответствие [Google JavaScript Style Guide](http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml).</li>
|
||
</ul>
|
||
|
||
Все они также доступны в виде программ, которые можно скачать.
|
||
|
||
## Итого
|
||
|
||
Описанные принципы оформления кода уместны в большинстве проектов. Есть и другие полезные соглашения.
|
||
|
||
Следуя (или не следуя) им, необходимо помнить, что любые советы по стилю хороши лишь тогда, когда делают код читаемее, понятнее, проще в поддержке.
|
||
|