Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
159 lines (128 loc) · 5.3 KB

CONTRIBUTING.md

File metadata and controls

159 lines (128 loc) · 5.3 KB

Руководство по оформлению кода

1. Структура файла

1.1. Заголовок файла

Каждый файл должен начинаться с заголовка в формате:

"""ТИП: краткая смета"""

Типы файлов:

  • VIEW — модули с классами arcade.View (экраны игры)
  • MODULE — основные модули и пакеты
  • UTILS — вспомогательные модули, утилиты
  • CONFIG — конфигурационные файлы
  • MODEL — классы данных, модели

1.2. Порядок секций в файле (если применимо)

  1. Заголовок файла
  2. Импорты (стандартные, сторонние, локальные)
  3. Константы
  4. Классы
  5. Функции
  6. Точка входа (если это главный файл)

2. Система комментариев

2.1. Специальные пометки

Используйте стандартные аннотации для задач и проблем:

# TODO: Добавить поддержку нескольких слоев тайлов
# FIXME: Исправить утечку памяти при частом зуммировании
# HACK: Временное решение для совместимости со старой версией
# NOTE: Важное замечание по архитектуре
# OPTIMIZE: Возможность улучшения производительности

Правила:

  • Все специальные комментарии пишите на английском языке
  • Указывайте дату и автора для FIXME/HACK: # FIXME(v.ivanov 15.12.2023): ...
  • Регулярно проверяйте и актуализируйте TODO-списки

3. Стиль именования

3.1. Классы — ВерблюжийРегистр (CamelCase)

class GameView(arcade.View):
class PlayerCharacter(arcade.Sprite):
class ResourceManager:

3.2. Методы и функции — змеиный_регистр (snake_case)

def calculate_damage(self):
def load_textures():
def setup_scene():

3.3. Приватные методы — начинаются с _

def _process_collision(self):    # Внутренний метод класса
def _validate_data(data):        # Внутренняя функция модуля

3.4. Константы — ВЕРХНИЙ_РЕГИСТР

SCREEN_WIDTH = 800
SCREEN_HEIGHT = 600
DEFAULT_FPS = 60

3.5. Переменные и атрибуты — змеиный_регистр

player_health = 100
current_score = 0
is_game_active = True

4. Документация

4.1. Комментарии в коде

  • Объясняйте почему, а не что (код должен говорить сам за себя)
  • Избегайте тривиальных комментариев: x += 1 # Увеличиваем x на 1
  • Используйте комментарии для неочевидных решений и сложной логики

5. Форматирование кода

5.1. Соблюдайте PEP 8

  • Отступы: 4 пробела
  • Пустые строки для разделения логических блоков

5.2. Импорты (группировать и сортировать)

# Стандартная библиотека
import os
import sys
from typing import List, Optional

# Сторонние библиотеки
import arcade
import numpy as np

# Локальные модули
from utils.helpers import load_config
from .constants import SCREEN_SIZE

6. Принципы написания кода

6.1. Функции и методы

  • Одна функция — одна ответственность
  • Не более 3-4 параметров на функцию (используйте dataclasses для сложных случаев)
  • Четкие и понятные названия

6.2. Обработка ошибок

# Правильно
try:
    config = load_config(path)
except FileNotFoundError:
    logger.error(f"Конфиг не найден: {path}")
    config = get_default_config()
except json.JSONDecodeError as e:
    raise ConfigError(f"Ошибка парсинга конфига: {e}")

# Неправильно
config = load_config(path)  # Может упасть без пояснений

6.3. Магические числа и строки

# Плохо
if x > 100:
    player.health = 100

# Хорошо
MAX_PLAYER_HEALTH = 100
if x > MAX_PLAYER_HEALTH:
    player.health = MAX_PLAYER_HEALTH

7. Комментарии

# === комментарий, дающий сводку большого блока кода
# - комментарий, объясняющий блок кода, функцию
def setup() -> Optional[bool]:
    x = load('map.json') # комментарий, поясняющий строку
    return True

def start(map: Map) -> Map:
    return map.__init__()

# -- комментарий к классу
class MapConfig:
    def __init__(self):
        pass