Следуйте руководству по стилю

Следуйте руководству по стилю

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

Руководство по стилю для вас и вашей команды В этом руководстве рассматриваются наиболее распространенные соглашения, с которыми вы столкнетесь при разработке на Unity. В основном это подмножество рекомендаций Microsoft Framework Design Guidelines, содержащих гораздо больше правил, чем представлено здесь. Это рекомендации, а не незыблемые правила. Адаптируйте их к предпочтениям своей команды. Выберите стиль, который устраивает всех, и следите за его соблюдением. Главное — единообразие. Если в будущем руководство по стилю потребуется изменить, несколько операций поиска и замены позволят быстро обновить всю кодовую базу.

Если ваше руководство по стилю расходится с этим документом или Microsoft Framework Design Guidelines, приоритет следует отдать собственному руководству: так команда сохранит единый стиль во всем проекте.

Приложение — общий результат труда людей, которые могут мыслить по-разному. Руководство по стилю сглаживает эти различия и помогает создать цельный продукт. Сколько бы участников ни работало над проектом Unity, код должен выглядеть так, словно его написал один автор.

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

Если вы работаете в одиночку, поначалу это может казаться ограничением, однако в командной разработке руководство по стилю необходимо. Считайте руководство по стилю первоначальным вложением, которое окупится позднее. Единый набор стандартов сокращает время на повторное освоение правил, когда разработчик переходит в другой проект. Microsoft и Google предлагают подробные руководства-примеры, которые принято считать отраслевыми стандартами: — Соглашения Microsoft по написанию кода C# — Руководство Google по стилю C# Они служат отличной отправной точкой для разработки на Unity и предлагают решения по именованию, форматированию и комментированию кода. В Unity мы не навязываем единый стиль кода всем учебным материалам для начинающих, документации и примерам проектов. Строгое руководство может усложнить обучение новичкам, тогда как большим командам и сложным проектам нужны более жесткие правила. У человека, который только осваивает Unity и, возможно, свой первый язык программирования, совсем иные потребности, чем у инженерной организации из более чем 2000 сотрудников.

Поэтому здесь используется стиль, расширяющий Microsoft Framework Design Guidelines, где определен ряд правил, не вошедших в этот документ. Он близок к стилю наших инженерных команд и авторов документации и, на наш взгляд, подходит большинству проектов Unity: в нем прагматизм поставлен выше формальной строгости.

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

Follow a style guide

There are only two hard things in Computer Science: cache invalidation and naming things. – Phil Karlton, software engineer

A style guide for you and your team This guide focuses on the most common coding conventions you’ll encounter during Unity development. These are mostly a subset of the Microsoft Framework Design Guidelines, which include an extensive number of rules beyond what is presented here. These guidelines are recommendations, not hard and fast rules. Customize them according to your team’s preferences. Pick a style that suits everyone and ensure they apply it. Consistency is king. If you follow these suggestions and need to modify your style guide in the future, a few find-and-replace operations can migrate your codebase quickly.

When your style guide conflicts with this document or the Microsoft Framework Design Guidelines, it should take precedence over them because this will allow your team to maintain a uniform style throughout your project. Your application is the collective product of individuals who might think differently from one another. A style guide helps rein in those differences to create a cohesive final product. No matter how many contributors work on a Unity project, it should feel like it’s been developed by a single author. Style guides take the guesswork out of coding conventions and formatting. Consistent style then becomes a matter of following directions. If you’re a solo developer, this might feel like a constraint at first, but following a style guide is essential when working in teams. Think of a style guide as an initial investment that will pay dividends later. Maintaining a single set of standards can reduce the time spent on relearning if you move anyone onto another project. Microsoft and Google both offer comprehensive example guides which are generally considered to be the industry standards: —

Microsoft C# Coding Conventions

C# at Google Style Guide

These are excellent starting points for managing your Unity development and offer solutions for naming, formatting, and commenting. At Unity, we don’t enforce the same code style across all of our beginner tutorials, documentation and sample projects. The main reason for doing this is that a strict style guide can get in the way of the learning curve for beginner users vs a need to enforce more strict guidelines when working in large teams and more advanced use cases. There are simply different needs for someone just learning Unity and perhaps their first programming language, and engineering teams with 2000+ people. In this guide, we thus follow a code style that extends Microsoft’s Framework Design Guidelines, which defines a number of rules not covered by this document. This code style is closer to that which is used by our engineering and documentation teams, and what we believe will be well-suited for most Unity projects – a style that balances pragmatism over strictness. Ultimately, the key is to choose one that works for you and your team and maintain consistency throughout your project. We created an example C# style sheet that you can also use as a reference as you assemble your own guide. Feel free to copy and tweak it as needed. Let’s dive in.