Code Style Guides

Общие рекомендации

  1. Работая с кодом, стремитесь повышать его качество. Если быстрый фикс ухудшает качество кода, запланируйте рефакторинг.
  2. Помните, ваш код должен быть понятен не только вам, но и коллегам. Красота скрывается в простоте.
  3. Предпочитайте композицию вместо наследования.
  4. Остерегайтесь сразу создавать переиспользуемые компоненты (Reusable components)]. Лишний слой абстрации переусложнит его использование сейчас.

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

  • Комментарии пишем на русском языке.
  • Пишите в комментариях моменты, которые не очевидны при чтении кода, пеерчисление сайд-эффектов.
  • Высокоуровневые комментарии класса/модуля не должны описывать детали реализации. Если у класса есть отдельно интерфейс, комментарии пишите в интерфейсе.
  • Низкоуровневые комментарии описывают описывают код и должны отвечать на вопросы: "Что?" и "Почему?", а не "Как?".
  • Если багфикс требует написание сложного кода, в комментарии поставьте также номер задачи из JIRA.
  • Обновляйте комментарии одновременно с кодом, не дублируйте.

JavaScript

  • Стиль Airbnb, Airnb React. В виде NPM пакетов: tslint-config-airbnb, eslint-config-airbnb
  • Комментирование в формате JSDoc.

React

Новые проекты создаем с поддержкой typescript:

npx create-react-app  --typescript ./project-name

В проекте подключаем Prettier, Husky, конфиг tslint-config-airbnb:

npm install --save-dev prettier lint-staged tslint tslint-config-airbnb

Добавьте в package.json:

"husky": {
  "hooks": {
    "pre-commit": "lint-staged"
  }
},  
"lint-staged": {
    "{src,test}/**/*.ts*": [
      "prettier --write",
      "git add"
    ]
  },

В .prettierrc:

{
  "singleQuote": true,
  "arrowParens": "always",
  "trailingComma": "all"
}

В tslint.json:

{
  "extends": "tslint-config-airbnb",
  "rules": {
    "variable-name": [
      true,
      "allow-pascal-case"
    ],
    "import-name": [
      false
    ]
  },
  "linterOptions": {
    "exclude": [
      "config/**/*.js",
      "node_modules/**/*.ts",
      "**/*.json",
      "**/*.css",
      "**/*.sass"
    ]
  }
}```

Другие рекомендуемые практики

*  PropTypes не нужен, если используете интерфейсы TypeScript. Если же в проекте нет TS, выносите описание объектов (PropTypes.shape) в [отдельные файлы](https://www.freecodecamp.org/news/react-pattern-centralized-proptypes-f981ff672f3b/).


 

### Angular.JS

[Angular 1 Style Guide](https://github.com/johnpapa/angular-styleguide/blob/master/a1/README.md) 

### Vue.js

[Official Style Guide](https://vuejs.org/v2/style-guide/)
 


## PHP
Следуем соглашению [PSR-2](https://www.php-fig.org/psr/psr-2/)

В рамках проекта Keitaro, добавляются особенности:

1. Имена приватных переменных класса пишем с подчеркиванием `private $_somePrivateVar;`.
2. Имена приватных методов пишем с подчеркиванием `private function _somePrivateMethod() {}`.

Содержимое `phpcs.xml` для PHP_CodeSniffer:

```xml
<?xml version="1.0"?>
<ruleset name="PSR2C">
    <rule ref="PSR2"/>
    <arg name="colors"/>
    <description>Apliteni Coding Standard</description>
    <exclude-pattern>vendor/*</exclude-pattern>

    <rule ref="PSR2.Methods.MethodDeclaration.Underscore">
        <type>warning</type>
    </rule>
    <rule ref="PSR2.Classes.PropertyDeclaration.Underscore">
        <type>warning</type>
    </rule>
	<rule ref="PSR1.Methods.CamelCapsMethodName">
        <exclude-pattern>tests/*</exclude-pattern>
    </rule>
</ruleset>

Ruby

A community-driven Ruby coding style guide.

Golang

Go Linters

Используем GolangCI. Ставится локально таким образом:

$ go get -u github.com/golangci/golangci-lint/cmd/[email protected]
$ golangci-lint run

Go Modules

В проектах используем Go Modules для работы с зависимостями и "вендирим" в проекте все пакеты. Читайте How do I use vendoring with modules? Is vendoring going away?.

В CI включено по умолчанию GOFLAGS=-mod=vendor, поэтому перед пушем в репозиторий запустите:

go mod vendor

Shell

Google Shell Style Guide.

Makefile

  1. Рекомендуем заводить Makefile в каждом проекте, с унифицированными командами make dev, make test.
  2. Имя make-файлов Makefile.
  3. Имя таргетов через минус. Например, run-tests.
  4. Переменные окружения пишем в верхнем регистре. Пример, PROJECT_PATH
  5. Локальные переменные в нижнем с разделителем _. Пример, build_dir = $(PROJECT_PATH)/build
  6. Определения Phony targets пишем после самого таргета, вместо опредения в одном месте:

Правильно:

all: build test
.PHONY: all

Неправильно:

.PHONY: all build test
all: build test

CoffeeScript

CoffeeScript Style Guide

Книги

  1. A Philosophy of Software Design