Руководство по Fungus. Стандартное Кодирование

• Начало
• Блок-Схемы
• Блоки
• Переменные
• Рассказать историю
• Воспроизведение Аудио
• Система разговоров
• Уроки Сообщества
• Теги Текстового Рассказа
• Система Вариаций Текста
• Сохранение и Загрузка
• Советы по Кодированию
• Стандартное Кодирование
• Глоссарий
• Часто Задаваемые Вопросы
• Fungus Lua.

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

Этот документ посвящен решениям, которые мы приняли для проекта Fungus. Для получения общих советов по кодированию в Unity попробуйте 50 советов и рекомендаций для Unity.

Макет кода

Это типичное расположение класса в Fungus: 

using UnityEngine;
namespace Fungus
{
    /// <summary>
    /// Description of the component.
    /// </summary>
    public class MyComponent : MonoBehaviour
    {
        [Tooltip("Tooltip comment displayed in the editor.")]
        [SerializeField] protected float myProperty = 10f;
        protected virtual void MyMethod()
        {
            if (myProperty > 5f)
            {
                Debug.Log("A message");
            }
        }
        #region Public members
        /// <summary>
        /// Documentation comment for public property.
        /// </summary>
        public virtual float MyProperty { get; set; }
        /// <summary>
        /// Aspect ratio of the secondary view rectangle. e.g. a 2:1 aspect ratio = 2/1 = 2.0.
        /// </summary>
        public virtual void DoSomething()
        {
        }
        #endregion
    }
}

Что следует отметить:

• Все использующиеся объявления размещаются в вверху файла скрипта.
• Удалите все неиспользуемые объявления (можно легко определить их с помощью статического анализа кода - см. Ниже).
• Код времени выполнения идет в пространстве имен Fungus.
• Код редактора помещается в пространство имен Fungus.EditorUtils.
• Все открытые классы, структуры, перечисления и члены класса должны быть задокументированы с использованием комментариев xml.
• Вы можете задокументировать частных и защищенных членов, если хотите, но ВСЕ Публичные члены(Public members) должны иметь хотя бы краткий комментарий.
• Описания параметров и возврата являются необязательными, добавьте их, если считаете, что параметры требуют нетривиального объяснения.
• Сериализированные поля НИКОГДА не должны быть открытыми. Используйте свойство общедоступного метода доступа для доступа к полю, если требуется внешний доступ.
• Все сериализованные поля должны иметь атрибут Tooltip. Это удваивается как код документации для поля.
• Все методы должны быть объявлены виртуальными и использовать защищенные, а не частные. Это позволяет легко наследовать и расширять (за счет некоторой производительности).
• Все общедоступные члены класса (включая общедоступные статические типы и типы делегатов) должны быть помещены в область 'Public members' для легкого доступа.
• Скобки переходят на новую строку и используют пробелы исключительно вместо вкладок.

Лучшие Практики Кодирования

Это некоторые общие рекомендации при написании кода для Fungus. Если это идет вразрез с обычной рекомендуемой практикой кодирования (например, Assert), то это из-за проблемы в Unity, заключающейся в том, чтобы делать это «правильным образом»..

• Используйте статический анализатор кода в MonoDevelop. http://tinyurl.com/h7xqpwg
• Используйте стиль комментария c# xml. https://msdn.microsoft.com/en-us/library/b2s063f7.aspx
• Объявите все публичные перечисления в области имен, а не внутри класса. (Согласованность, облегчение разделения перечислений между классами).
• Используйте var вместо объявления типов переменных, когда это возможно. (Более читабельно).
• Используйте вместо foreach, когда это возможно. (Избегает выделения проблем с итераторами и GC).
• Используйте string.Format или StringBuilder вместо объединения строк. (Избегает распределения и проблем с GC).
• Не используйте LINQ. (Избегает распределения и проблем GC.)
• Не используйте Assert. (Мы поддерживаем до Unity 5.0, до появления Assert).
• Используйте Mathf.Approximately при сравнении переменных с плавающей точкой с константами.
• Обрабатывайте предупреждения компилятора как ошибки. Должны быть нулевые предупреждения при сборке или во время выполнения при нормальной работе.
• Добавить глобальные константы в FungusConstants.cs

Обратная совместимость

Мы стремимся поддерживать обратную совместимость с каждым новым выпуском (в разумных пределах).

• Проекты должны работать правильно после обновления до новой версии Fungus. Незначительные изменения поведения являются приемлемыми.
• Пользовательский код, использующий API-интерфейс Fungus, после обновления должен компилироваться без ошибок. Незначительные ошибки компиляции, которые тривиально исправить, иногда допустимы.
• В Интернете есть множество обучающих видео и статей по Fungus, поэтому избегайте слишком резкого изменения пользовательского интерфейса. Небольшие настройки интерфейса и добавление новых элементов управления является приемлемым.
• Мы поддерживаем Unity 5.0+, поэтому остерегайтесь различий API в новых версиях. Если вы сомневаетесь, установите Unity 5.0 и проверьте свои изменения.

Содействие

Мы приветствуем запросы от всех. Принимая участие в этом проекте, вы соглашаетесь соблюдать Кодекс поведения. Вы также соглашаетесь с тем, что, отправив запрос на извлечение для этого проекта, ваш вклад будет лицензирован по лицензии Open Source для этого проекта.

• Fork и clone Fungus repo.
• Убедитесь, что тесты пройдены локально (см. Readme проекта для инструкций).
• Сделай свое изменение. Добавьте тесты для вашего изменения. Сделайте тесты проходить локально.
• Нажмите на fork и отправьте запрос на извлечение.

Ваш запрос на получение с большей вероятностью будет принят, если вы сделаете следующее:

• Отправляйте по одному запросу для каждой новой функции / исправления ошибки. Просмотр многофункциональных изменений занимает много времени, и мы не объединим изменения, если не будем точно знать, что они делают.
• Написание тестов для каждого изменения / новой функции (не всегда возможно)
• Следуйте нашему стандарту кодирования (см. Выше)
•  Напишите  хорошее сообщение в сообщении.