Требования к разработке модели базы данных и оформлению кода

[Alex]

По поводу стиля. Где-то в сети мне попадалось руководство по оформлению кода от гугл. На мой взгляд, самое адекватное из подобных. Видно, что люди знают о чём пишут и каждое требование обосновано и выверено. Там отступы пробелами, 2 пробела, открывающая фигурная скобка на одной строке с функцией, пробел после for и т..д.

Я думаю вполне разумно взять стиль от гугл за основу оформления кода и не изобретать велосипед там, где эта работа уже проделана профессионалами.

Мысль в сторону. Форматирование кода это чистый формализм, неужели никто не изобрёл настраиваемый конвертер исходного кода? Пишешь как тебе нравится, а перед отправкой в сеть нажимаешь кнопку «отформатировать под стиль MajorDoMo». И никаких проблем.

[LutsenkoDenis]

На мой взгляд, самое адекватное из подобных. Видно, что люди знают о чём пишут и каждое требование обосновано и выверено. Там отступы пробелами, 2 пробела, открывающая фигурная скобка на одной строке с функцией, пробел после for и т..д.

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

1. Вы уверены в том, описанные в документе вещи писались за один вечер и/или составлялись не профессионалами? Или у Вас принцип - всё что от гугл это профессионально, если нет то не профессионально? Например есть PSR-стандарт. в нем четыре пробела, если уж всем хочется развести срач про пробелы. И что - люди которые входят в PSR не профессионалы?!

2. Про фигурные скобки и пробелы с отступами в документе всё написано.

3. За основу можно взять всё что угодно, главное следовать тому что взял.

4. Форматирование это формализм когда код пишет 1 человека.

[Alex]

Действительно, за основу можно взять всё, что угодно. Я — за стиль от гугл, он мне субъективно нравится больше других.

По поводу двух пробелов подозреваю, что дело в том, что это разумный компромисс между читаемостью кода, «разъезжанием» листинга вширь при большом уровне вложенности и минимизацией предаваемых файлов по сети. Я думаю именно поэтому у гугла 2 пробела, а не «просто так с потолка». Но это только моё предположение.

[LutsenkoDenis]

Краткие итоги по разногласиям с предлагаемым документом:

1. 1. По табам:
   В настоящий момент с небольшим перевесом выигрывает предложение использовать 2(два) пробела.
   • Tab = 4 пробела - 1 человек (Zelenova) причина: не указана
   • Tab = 3 пробела - 1 человек (LutsenkoDenis) причина: при большом уровне вложенности лучше читается чем 2 пробела и тем более чем 4.
   • Tab = 2 пробела - 2 человка (msh555, Alex) причина: разумный компромисс между читаемостью кода, «разъезжанием» листинга вширь при большом уровне вложенности и минимизацией предаваемых файлов по сети.

• 2. По самому документу(нужен или нет и если нужен то какой):
  • Alex: "Я думаю вполне разумно взять стиль от гугл за основу оформления кода и не изобретать велосипед там, где эта работа уже проделана профессионалами."
  • LutsenkoDenis: Полагаю, что предлагаемый документ содержит или будет содержать в последствии не только правила оформления самого кода, но и специфичные для проекта вещи. В связи с этим, считаю что брать за основу стиль гугл или кого-то еще конечно можно, но это должно быть отражено в данном документе(Либо целиком либо ссылкой на сторонний ресурс). Лично мне больше нравится стиль описаный в документе чем от гугл.

В настоящий момент других предложений/комментариев к документу набралось.

[LutsenkoDenis]

За прошедшую неделю никаких пожеланий/замечаний к документу не высказано. Я так понимаю что все со всем согласны.

В дополнении к вышеуказанному документу я создал новый проект на github - MajorDoMo-Coding-Standards.

Описание к нему я допишу в скором времени. Если коротко, то данный проект содержит:

• Набор правил для PHP CodeSniffer'a, для проверки на соответствие кода и требований описанных в документе.
• (Windows) Git pre-commit hook - Перед коммитом проводит проверку(с использованием PHP CodeSniffer) кода на соответствие требованиям описаным в документе.

Инструкция по установке PHP CodeSniffer'a под windows(xampp) - ссылка

Поправки к вышеуказанной инструкции:

• Скачать последнюю версию стандартов: https://github.com/palacex/MajorDoMo-Co ... master.zip
• Скопировать папку MajorDoMo в папку со стандартами PHP CodeSniffer'a: Для xampp это: \xampp\php\pear\PHP\CodeSniffer\Standards
• (Windows)Скопировать файл pre-commit в .git/hooks, открыть его редактором и проверить соответствие путей к powershell и codesniffer'у.

Теперь, при попытке закоммитить новый или изменённый php файл, будет проводится проверка этого файла на соответствие требованиям описанным в документе. Если файл не соответствует требованиям, то коммит сделать не получится и будет показан лог проверки со списком ошибок.

[LutsenkoDenis]

Небольшое обновление и новые пожелания/замечания к документу.

Обновление
Добавил описание по установке и использованию PHP Code Sniffer на странице правил. MajorDoMo-Coding-Standards

Пожелания/замечания к документу.
Выбор стиля фигурных скобок. Варианты:

• Kernighan/Ritchie (K&R)

  Код: Выделить всё

  <?php 
    if($flag){ 
      echo "Hello world!"; 
    } 
  ?>

  (+) Экономия вертикального пространства, жизненно важная при отладке большого блока кода.
  (-) Трудно найти символ {, спрятанный в конце строки.
• Eric Allman (BSD)

  Код: Выделить всё

  <?php 
    if($flag) 
    { 
      echo "Hello world!"; 
    } 
  ?>

  (+) Область видимости блочного оператора ясна и визуально ассоциируется с управляющим оператором.
  (-) Нет экономии вертикального пространства

p.s. В текущей редакции документа и правил снифера используется стиль BSD.

[sergejey]

Большинство (все?) современные IDE поддерживают как подсветку парных скобок так и code folding, так что искать символ { долго не приходится. Экономия вертикального пространства -- ну не плюс и не минус. Мониторы, благо, уже не 15-ти дюймовые. На вкус и цвет, но я привык скобку оставлять в конце строки, а не на отдельной строке.

[LutsenkoDenis]

code folding и подсветка это хорошо, но всё равно не сильно помогает с фигурной скобкой. это затрудняет визуально выделить блок оператора. Т.е. визуально хуже читается структура. Но это мое мнение. На истину в последней инстанции я не претендую.