Какой стиль программирования выбрать, чтобы не вникать спустя время в проект?

Question

[Max Ba]

Речь исключительно о php.
Написал класс для работы с определенной моделью. Как правило, это методы по работе с БД по данной модели.
Через год надо что-то поправить, внести изменения и долго времени уходит на "вспомнить как оно работает".
И часто бывает, что времени на это "вспомнить" уходит прилично.
Может есть какие-то общие правила для написания такого кода, который налету понятен?

Comments

[kafkiansky]

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

[Konata Izumi]

Добавлю SOLID, DRY, док блоки (указание типов аргументов очень помогает), соблюдать psr код стайл или код стайл конкретного проекта/команды

[Максим Федоров]

Использовать фреймворк (в смысле на котором вы всегда работаете) и однородный стиль работы с конкретным слоем, чтобы не вникать, а сразу ЗНАТЬ как поправить...

[Max Ba]

Ну тут я еще может напортачил.
К примеру метод update принимает массив
Выглядит это так:

public funftion update(array $param){

}

И как выяснилось, МОЙ ЖЕ!!!! код и сохраняет и обновляет одним методом. Отличается запрос лишь тем, передаю ли я в массиве параметр id => 1 или нет. Я долго матерился конечно)

[Виталий Хоменко]

Дополню еще одним советом:
Писать самодокументируемый код, комментарии для которого не нужны. Исключением являются ситуации, когда используется сложная и/или не очевидная логика. Самодокументирование это такой подход к написанию кода, когда имена переменных говорят о том, что они в себе содержат, а имена функций и методов о том, что они делают. Код строится просто и линейно, чтобы разработчик сразу понимал, что делает та или иная часть и что именно тут содержится.

[Сергей delphinpro]

Мне обычно хватает doc-блоков, по которым по-быстрому генерится документация.
Главное не забывать писать doc-блоки =)

[Александр]

Читайте "Чистый код" и будет вам счастье. Это, пожалуй, библия для программиста.

Answer 1

[Иван Шумов]

Документацию писать надо) вот и весь секрет

Comments

[Евгений Ромашкан]

Документировать что делает класс или метод - бред.

[kafkiansky]

Евгений Ромашкан, а что не бред?

[Иван Шумов]

Евгений Ромашкан, нет

[Сергей delphinpro]

Евгений Ромашкан, а что нужно документировать?

[Александр]

Хороший код не нуждается в документации.

[Иван Шумов]

Александр, как же ты заблуждаешься)

[Александр]

Иван Шумов, это не конструктивно. Прошу пример.

[Иван Шумов]

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

[Евгений Ромашкан]

mad_maximus, Не бред писать самодокументирующийся код.

[Евгений Ромашкан]

Иван Шумов,
Документация никак не поможет если код пишется так что его невозможно разобрать.

mad_maximus, А ещё не бред - иметь один источник правды, а не разводить их за зря и все-равно в итоге лезть в код.

[Евгений Ромашкан]

Сергей delphinpro, То что невозможно выразить в коде.

[Иван Шумов]

Евгений Ромашкан, мы, видимо, с разными фреймворками работали. У меня все с достаточной документацией

[Евгений Ромашкан]

Иван Шумов, Да фиг с ними с фреймворками, я вырезал тот абзац, меряться *** не конструктивно. Дописал про источники правды.

[Иван Шумов]

Евгений Ромашкан, про неразборчивый код отлично сказано

Answer 2

[Anton Kuzmichev]

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

Answer 3

[index0h]

Попросили проверить код, на что смотреть нужно?

Answer 4

[sim3x]

TDD

Забыли, что делает проект
Запускаем тесты
Смотрим, возможно остались ошибки с todo
Фиксим их
По пути смотрим на юзерстори
Находим место, где требуется внести правку в юзерстори
И далее по циклу

Если вы не понимаете, что написано в вашем классе - значит он написан плохо
Перепишите его, так чтоб с первого взгляда на код вы могли понять, что он делает

Comments

[Антон Шаманов]

и как ему это поможет в описываемой ситуации?

[sim3x]

Антон Шаманов,

Запускаем тесты
Смотрим что упало
Пишем фикс

[Антон Шаманов]

sim3x, капитан очевидность снова с нами, ураа!

Через год надо что-то поправить, внести изменения и долго времени уходит на "вспомнить как оно работает".

и как ему это поможет в описываемой ситуации?

[sim3x]

Антон Шаманов,

Вам описать, как юзерстори помогут человеку вернуть понимание проекта?
Или что-то еще?

[Антон Шаманов]

sim3x, у "юзерстори" айдентити какой?

[sim3x]

Антон Шаманов, ?

[Антон Шаманов]

sim3x, чего тут непонятного? я тоже придумал какой-то известный только мне термин и аппелирую к нему :) хочешь чтобы тебя понял говори развернуто и по возможности по русски

[sim3x]

Антон Шаманов,
Я не пишу на 1с

Вам описать, как юзерстори помогут человеку вернуть понимание проекта?
Или что-то еще?

[Антон Шаманов]

sim3x, мы даже как-то термин придумали - "чепуховедение" :)

[sim3x]

Антон Шаманов,

Да, я тоже не сильно люблю 1с

Я так понимаю, что вопросов по сути больше нет

[Vitsliputsli]

Антон Шаманов, user story устоявшийся, я бы даже сказал стандартный термин в разработке, почитайте, Google сможет подробнее рассказать.

[Антон Шаманов]

Vitsliputsli, развелось блин попугаев, увидят знакомое слово и ко-ко-ко. Какая связь у TDD и user story?

[sim3x]

Антон Шаманов,

Прямая
Функциональные тесты пишутся по юзерстори

[Vitsliputsli]

Антон Шаманов, ты же заявил, что это слово выдумали и никто его не знает, а сейчас пишешь, что оно всем знакомо. И о каких связях user story спрашиваешь, если не знаешь что это? Так что вперед, самообразовывайся, google в помощь.

Answer 5

[Антон Шаманов]

комментарии к коду особенно в местах с нестандартными хаками очень помогают ) вроде "эта строка тут нужна чтобы обеспечить совместимость со старыми версиями метода x"
+ длинные функции/методы - зло - пусть отдельный метод и не служит для избавления от дублирования кода, но он увеличивает читабельность кода