# 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) в отдельные файлы.

# Angular.JS

Angular 1 Style Guide

# Vue.js

Official Style Guide

# PHP

Следуем соглашению PSR-2

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

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

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

<?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 init [имя проекта]
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. Создаем make help:

    help: ## Display this help @awk 'BEGIN {FS = ":.##"; printf "\nUsage:\n make \033[36m\033[0m\n\nTargets:\n"} /^[a-zA-Z_-]+:.?##/ { printf " \033[36m%-10s\033[0m %s\n", $$1, $$2 }' $(MAKEFILE_LIST)

    test: ## Run tests go test ./..

# CoffeeScript

CoffeeScript Style Guide

# Книги

  1. A Philosophy of Software Design