Как писать хороший код: стиль, нейминг, комментарии и структура

Соблюдайте единый стиль оформления

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

Отступы

Используйте отступы одинаковой ширины — чаще всего это 2 или 4 пробела. Никогда не смешивайте пробелы и табуляцию.

Форматирование блоков

Скобки, переносы строк, пробелы между операторами — всё должно быть единообразно.

if (isValid) {
	processData();
} else {
	handleError();
}

Курс изучения Python

Можете пройти наш бесплатный курс по изучению Python

Ограничение длины строки

Не стоит писать строки длиной в 300 символов. Чаще всего хорошим правилом является ограничение до 80–120 символов.

Давайте переменным и функциям осмысленные имена

Название переменной должно отражать её назначение. Не стоит использовать имена вроде x, data или tmp, если можно дать более точное название.

Плохой пример:

a = 10 
b = get(x) 

Хороший пример:

max_retry_attempts = 10 
user_profile = get_user_profile(user_id) 

Именование функций тоже важно. Функция должна отвечать на вопрос: «что она делает?»

# Плохо
def handle():
	pass

# Хорошо
def handle_user_login():
	pass

Используйте глаголы в функциях (например: send_email, calculate_sum) и существительные в переменных (email_address, user_profile).

Пишите комментарии с умом

Комментарии должны дополнять код, а не дублировать его. Избегайте комментариев вроде:

// Увеличиваем счетчик на 1
counter = counter + 1;

Лучше комментировать "почему", а не "что":

// Нужно сделать +1, так как цикл должен включать последний элемент
counter = counter + 1;

Используйте TODO, FIXME и другие метки, если нужно пометить временные решения или баги:

// TODO: заменить на асинхронную загрузку
loadUserData();

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

Разбивайте код на логические блоки

Один файл — одна логика. Один класс — одна ответственность. Одна функция — одно действие. Это базовые принципы чистой архитектуры и SOLID.

Разделяйте функции

Если функция стала слишком длинной (более 30–50 строк), подумайте о разделении её на несколько.

Группируйте код

Разделяйте логические блоки пустыми строками и комментариями — это помогает быстро понять структуру.

def process_user_data(user):
	# Шаг 1: валидация
	if not is_valid(user):
		raise ValueError("Invalid user")

	# Шаг 2: обновление профиля
	update_profile(user)

	# Шаг 3: отправка уведомления
	send_notification(user)

Создавайте понятную структуру проекта

Структура проекта должна быть логичной и предсказуемой. Вот несколько правил:

• Храните файлы по категориям: controllers, models, services, utils.
• Выносите конфигурации в отдельные файлы.
• Избегайте вложенности более 2–3 уровней.
• Пишите README с инструкциями по запуску проекта.

Курс изучения C#

Можете пройти наш бесплатный курс по изучению C#

Пример структуры на Python:

project/
├── app/
│ ├── controllers/
│ ├── models/
│ ├── services/
│ └── utils/
├── config/
│ └── settings.py
├── tests/
├── requirements.txt
└── README.md

Используйте линтеры и форматтеры

Автоматические инструменты помогают поддерживать единый стиль во всем проекте. Примеры:

• JavaScript: ESLint, Prettier
• Python: Black, Flake8
• Go: gofmt, golangci-lint
• PHP: PHP_CodeSniffer, PHP-CS-Fixer

Настройте автозапуск линтера при коммитах с помощью husky или pre-commit хуков.

Заключение

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