Что бы вы предпочли?
Умный код, который работает, но его трудно понять, или хорошо написанный код с комментариями, который легко понять, но не работает?

Это будет короткий и простой пост.
Сколько времени вы тратите на расширение/чтение чужого кода?

Уважаемый «умный» программист, знайте, я когда-то был таким, как вы. Я не стал менее умным, я просто понял, что сегодня нет смысла писать «Умный» код, который запутает меня, когда я буду смотреть на него через три часа. Серьезно, в жизни есть нечто большее, чем тратить бесчисленные часы, пытаясь понять свой собственный код, потому что я не был «Умным».

Лучший способ писать код (даже если вы думаете, что он предназначен только для ваших глаз) — это делать его так, чтобы другие программисты поняли его почти с первого взгляда.

Будьте либеральны с комментариями.
Лучше всего описать фрагмент кода как можно подробнее.
Используйте многострочные комментарии /** */ непосредственно перед функциями, чтобы описать назначение кода, аргументы и типы возвращаемых значений настолько подробно, насколько это целесообразно.
Это особенно облегчает жизнь, когда вы используете хорошие IDE, такие как NetBeans.
Примечания отображаются в виде подсказок при вызове функций и помогают успокоить пользователя. программисту, что он/она вызывает правильную функцию.

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

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

$first_name = "john";
лучше, чем
$fname="john";

Помимо описательного именования переменных, обратите внимание на пробелы вокруг оператора присваивания «=».

Вот пример php-кода на gitlab, который показывает пример того, как это можно сделать.

Это лучше всего применять, даже если вы работаете с другими языками, такими как C++, Java, или работаете с такими фреймворками, как Laravel или Symfony.

Хороший поддерживаемый код делает счастливыми больше программистов и делает мир более спокойным.