MajorDoMo

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

MajorDoMo style Guide

p.s. Документ выложил в виде pdf.
По итогам обсуждения и принятия данного документа как стандарта для нашего проекта, содержимое лучше выложить на гитхабе проекта с примерами правильного и неправильного оформления кода.

Каждую пятницу я буду перечитывать эту ветку форума и создавать пост с промежуточными итогами.

Отлично!!! Давно пора реализовывать.
Хотелось бы настоять на Tab = 4 пробела.

3.Закрывающий тэг «?>» необходимо удалять из файлов содержащих только PHP

то есть в начале файла "<?php", а в конце не закрываем?
Или я невнимательно прочитал.

Ну и не критично но, перед "(" пробел не ставим? При использовании функций и всяких for...

Надо еще несколько раз перечитать.

Завершающий тэг PHP ?> не обязателен и для улучшения совместимости с некоторыми системами может быть опущен.


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

В моем случае, 4 слишком много, а 2 мало(при описании метода с параметрами начинающимися с новой строки(не на php) параметры сливаются с именем метода.).

Хороший документ.

Лично для меня не очень освещен вопрос с расстановкой { и } в конструкциях if...else, switch...case, for, while и описании функций. Т.е. c с новой строки или нет, какие отступы опять же, и т.п.?

Я правильно понял, что эти требования распространяются именно на исходный код проекта (ядро) и его модули? А в методах, сценариях, домашних страницах, коде к элементам меню останется по-прежнему "кто во что горазд"?

MajorDoMo style Guide

Дописал про расстановку переносов и инструкции if-else и т.д.

Мне бы хотелось, чтобы эти требования распространялись на всё(на ядро, модули, сценарии с методами, базу данных и т.д.).

Но если с ядром можно сделать так: всё что попадает на github должно строго соответствовать.
То методы каждый пишет под себя и соответственно с ними получится всё равно "кто во что горазд". Единственное что будет некий "Документ", куда человек может посмотреть и привести свой метод к тому что описано в документе.

MajorDoMo style Guide
Добавил про оформление SQL-запросов.

Еще, пожалуй, вопрос применения двойных и одинарных кавычек актуален. В тех же say(), getGlobal(), setGlobal() расброд и шатание.

У меня вопрос. Может перенести из PDF-ки в ВиКи?

А по самому документу...
Дело нужное, но кропотливое. И бестолковое.
Странно, что Сергей не отписался в теме.
Я ставлю два пробела. Все несогласные идут в бьютефайлер.
Есть места где необходимо использовать одинарные ковычки внутри двойных.
Многострочное форматирование SQL кода должно быть оправдано, если помещается в экран - лучше не бить.
и тд. и тп.
Самая большая ошибка документа - это требования, а должно называться рекомендации.
Каждый программист сообщества важен более чем код, который он пишет. Именно поэтому нельзя навязывать стиль программирования.
Более того - у многих вещей (маркет к примеру) есть авторы, и они в своем авторском праве писать как заблагорассудится.
Вместо рефакторинга предлагаю заняться написанием новых модулей для маркета (по темам - куча заказов).

Прошу прощения, если мое мнение не совпадает с мнением топикстартера

msh555 писал(а):У меня вопрос. Может перенести из PDF-ки в ВиКи?
А по самому документу...
Дело нужное, но кропотливое. И бестолковое.
Странно, что Сергей не отписался в теме.
Я ставлю два пробела. Все несогласные идут в бьютефайлер.
[...]
Прошу прощения, если мое мнение не совпадает с мнением топикстартера

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

MajorDoMo style Guide
Добавил про кавычки.

msh555 писал(а):У меня вопрос. Может перенести из PDF-ки в ВиКи?

На текущий момент времени так лучше. После принятия документа, хотелось бы в вики сделать ссылку а всё содержимое документа на гитхаб как markdown документ. Например как тут

msh555 писал(а):Дело нужное, но кропотливое. И бестолковое.

На счёт бестолкового - зависит от того, как к этому процессу подойти.

msh555 писал(а):Странно, что Сергей не отписался в теме.

Считаю что если не отписался, значит согласен. Но на сколько я помню он отписывался.

msh555 писал(а):Я ставлю два пробела. Все несогласные идут в бьютефайлер.

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

msh555 писал(а):Самая большая ошибка документа - это требования, а должно называться рекомендации.

На название документа я не претендую. Но оно более точно характеризует документ. Тем более что требования могут быть как жёсткие так и нет.

msh555 писал(а):Каждый программист сообщества важен более чем код, который он пишет.

Отчасти согласен. Но каждый программист должен придерживаться общего стиля который принят в проекте и уважать других программистов участвующих в разработке.

msh555 писал(а):Более того - у многих вещей (маркет к примеру) есть авторы, и они в своем авторском праве писать как заблагорассудится..

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

msh555 писал(а):Вместо рефакторинга предлагаю заняться написанием новых модулей для маркета (по темам - куча заказов)

Я не предлагаю всё сразу бросить и заняться рефакторингом, но к сожалению в коде системы столько всего намешано, что без рефакторинга уже никак. А данный документ, как раз позволит выдержать в едином стиле как новый код, так и отрефакторенный. В результате это повысит как качество кода так и легкость его чтения.

Как я писал в самом начале, я составляю документ с общими требованиями(рекомендациями) по написанию кода. То что я в документе написал - обсуждаемо, но скажем в течение месяца-двух. Далее должно быть принято как стандарт в нашем проекте. Естественно, со временем в него могут вносится какие-то изменения.

Также я писал, что каждую пятницу, я буду подводить краткие итоги по аргументированным мнениям/пожеланиям, тех чье мнение разошлось с тем что написано в документе. Например если брать отступы, то: 2 пробела - 2 человека, 3 пробела - 1 человек, 4 пробела - 1 человек. Т.е. пока два пробела побеждают.