Начнем сначала
Хороший код начинается с одного — ясности.
Не с архитектуры. Не с паттернов. А с того, как вы называете переменные, функции, классы. Потому что читать код — важнее, чем писать. В 90% случаев вы будете не творить, а разбираться.
Есть четыре признака хорошего кода:
Читаемость, изменяемость, безопасность, производительность.
Последнее — на потом. Первые три — критичны. А из них главная — читаемость.
Если код не читается — он не живёт.
Теперь к делу.
Десять правил, как называть вещи своими именами
1. Не скупитесь на смысл
maxAttempts — отлично.
m, c, counter — мусор.
Имя должно объяснять, что это, без комментариев.
2. Не надо «инфо»
value, info, data, object — это как назвать собаку «Животное».
userEmail, invoiceNumber — сразу понятно, про что речь.
3. Длина по важности
i — годится, если живёт одну строчку.
Живёт дольше — давайте имя, как человеку: с уважением и смыслом.
4. Говорите на понятном языке
Ваш бизнес — это и есть ваш словарь.
tin, vat, invoiceId — это хорошо.
var3 — это провал.
5. Убивайте магические числа
5 — ни о чём.
MAX_RETRIES = 5 — всё ясно.
Давайте именам контекст. Это бесплатно.
6. Меньше отрицаний
isNotValid — мозг спотыкается.
isValid — и просто, и читаемо.
Проверку !isValid — видно с первого взгляда.
7. Имя должно звучать
Если вы не можете произнести название — выбросьте его.
Код обсуждают словами. А не угадыванием, как это читается.
8. Не затеняйте язык
list, map, range — звучит как ловушка.
Сегодня — переменная. Завтра — конфликт. Не надо.
9. Время — это важно
createdAt, deletedAt, updatedAt — всё по порядку, всё по-человечески.
date — это ни о чём. Какая дата? Чья дата?
10. Договоритесь и не спорьте
Один стиль — экономия жизни всей команды.
Разнобой = спагетти.
Решили — соблюдайте.
Примеры. Чтобы стало совсем понятно
Хорошо:
Product::getPrice() — сразу видно, что делает.
Очень хорошо:
Model::firstOrCreate(attrs, values) — магия Laravel.
Прочитал — понял, что сначала ищет, потом создаёт.
Плохо:
uploadArrayImage(models, collection_name, nameColumn, review)
Что делает? Для чего? Почему так называется? Бред.
Ещё хуже:
Salary::calculate()
Что считает? Брутто? Нетто? В час? В секунду? В фантиках?
Вместо вывода
Вы — это то, как вы называете вещи.
Хороший код — как хороший текст: не бесит, не путает, не ломается.
Пишите так, будто за вами будут читать. Потому что будут.