Манифест об организации кода в QSP

Внимание!!!

Это только черновик манифеста. Он ещё будет дорабатываться до полноценной статьи.

подсказка

Тип кортежей обрёл своё обозначение в QSP, поэтому теперь не нужно выделять кортежи нижним подчёркиванием спереди

Этот манифест объявляю исключительно я, Aleks Versus. Следовать ему или не следовать, ваше право, поскольку каждый стилизует код под себя. Однако, если вы разрабатываете модуль, использование которого предполагается другими людьми, или совместно работаете над игрой, необходимо вывести стандартные правила оформления кода.

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

Повторюсь. Это лишь рекомендации по оформлению. Строго следовать им не нужно. В каждом конкретном случае подходите к написанию с умом и старайтесь делать код более читаемым. Хотя бы для себя.

Запись команд

Команды следует писать в отдельных строках. Допустимо объединять в одной строке две-три команды, если они очень короткие.

Правильно:

square = a * b
volume = square * height

Допустимо:

square = a * b   &   volume = square * height

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

Недопустимо, потому что нечитаемо:

square = a * b   &   volume = square * height  &   space = volume * 23 + dev   &  *pl space/square  &  *nl  &  *p "end of math."   &  ! ещё и комментарий

Так же допустимо объединять команды при заполнении каких-то структурных данных. Например, вы заполняете таблицу, разнося её по массивам. Тогда имеет смысл объединять в одной строке несколько команд, чтобы таблица была наглядной:

$id[0]='0001' & $object[0]='Старый меч' & power[0]=100    & stam[0]=255
$id[1]='0002' & $object[1]='Старый нож' & power[1]=50    & stam[1]=137
$id[2]='0003' & $object[2]='Старый ган' & power[2]=99    & stam[2]=123
$id[3]='0004' & $object[3]='Клиган-бой' & power[3]=9999 & stam[3]=999

В этом случае приходится обрамлять разделители команд дополнительными пробелами, чтобы выровнять "столбцы".

Однострочные и многострочные конструкции

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

Допустимо использовать однострочные конструкции, если у вас не более двух команд, либо если вторая или третья команда, это exit, goto или комментарий.

Именование переменных

Однобуквенные переменные, в т.ч. переменные типа $y или $z, никогда не используются как глобальные.

Если нужна многобуквенная локальная переменная в конце её названия ставим символ нижнего подчёркивания, так мы сразу будем понимать, что используемая в коде переменная является локальной.

Поскольку типы кортежей и строк фактически неразличимы необходимо начинать названия переменных кортежей с символа нижнего подчёркивания.

Примеры:

! объявляем локальные переменные числового и текстового типов

local x, $z, $many_letter_
! объявляем кортеж (глобальный)

$_tuple = ("Вася",34,182,90,"боксёр")
! объявляем локальный кортеж

local $_personage_ = $_tuple

Аналоги констант и игровые переменные для хранения глобальных настроек пишутся заглавными буквами.

Неявный вызов функций

Если неявно вызываемая функция не имеет аргументов, но возвращает значение, обязательно ставьте скобки за её именем. И напротив: если функция не возвращает значения и не имеет аргументов, скобки ставить не следует. Так будет проще отличать функции от процедур.

https://pythonworld.ru/osnovy/pep-8-rukovodstvo-po-napisaniyu-koda-na-python.html#section-30