Соглашения о кодировании

Общие положения соглашений о кодировании.

1 Цели правил кодирования

• Единый стиль оформления кода во всем проекте.
• Визуальное выделение наиболее значимых частей.

2 Соглашения об именовании

2.1 Именование переменных

• Существует несколько популярных соглашений об именования переменных:
  • Верблюжья нотация (CamelCase): MyClass
  • Змеиная нотация (snake_case): my_const
  • Шашлычная нотация (kebab-case): my-data
  • Венгерская нотация - соглашение об именовании идентификаторов (переменных и функций), которое сводится к кодированию типов данных прямо в название: userArray.
  • Нотация Cobol: COBOL-CASE.

2.2 Предикаты

Предикат - это функция-проверка, она всегда возвращает либо true, либо false.

• Предваряются префиксом is: isEmpty().
• Если предикат отвечает на вопрос есть ли? (например, есть ли в списке чисел нечётное число?), принято использовать слово has: hasChildren().
• Используется знак ? в конце слова (lisp, ruby): empty?.
• Используется буква p в конце слова (emacs lisp): empty-p.

2.3 Разное

2.3.1 Количество

Если нужна переменная, в которой содержится количество чего-либо, используется комбинация: сущность во множественном числе + count: symbolsCount.

3 Отступы

• Во многих стандартах кодирования запрещается использовать табуляции - их требуют заменять пробелами.
• В различных редакторах может устанавливаться разная длина символа табуляции, поэтому при смешении табуляции с пробелами исходный код будет выглядеть по-разному в разных редакторах.

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

• Комментарий - некомпилируемая часть исходного кода, поясняющая принцип работы программы.

• Иногда в комментариях фиксируют информацию:

  • о версии кода и, внесенных в ней, изменениях;
  • об авторе кода или конкретных правок;
  • о лицензии, по которой распространяется код;
  • о неисправленных ошибках и прочих недочетах, заметки разного рода.

• Комментарии должны быть коггерентны коду. При изменении кода надо менять комментарии.

• Комментарии не должны пояснять очевидные моменты.

• Комментарии должны быть понятны всем, а не только тем, кто их пишет.

• Комментарии не должны содержать бесполезной информации.

• Написание комментариев и поддержка единого стиля комментариев не должна отнимать слишком много времени.

• Использование современных инструментов разработки позволяют полностью исключить некоторые типы комментариев из программы:

  • информацию о версии программы, авторе изменений и ее особенностях позволяют хранить системы управления версиями;
  • комментарии TODO, BUG и FIXME могут быть перенесены в трекеры задач и ошибок.