Руководство по стилю Google

Вы вынуждены придерживаться руководящих принципов компании, установленных в камне в 1969 году? Или ваши коллеги-разработчики могут выразить свою художественную сторону встроенным ASCII-искусством?

Мне нравится просматривать руководящие принципы стиля. Обычно существуют очевидные правила, которые кажутся странными, и несколько скрытых драгоценных камней, которые вы раньше не открывали. К сожалению, немногие компании достаточно смелы, чтобы опубликовать внутренние рекомендации. Би-би-си представила свои документы в 2010 году, но Google наконец-то выпустил руководства по стилю, которые компания использует для внутренних проектов.

Правила предоставляются для C ++, Objective C, Python, XML и R – но нас больше всего интересуют HTML, CSS и JavaScript. Документы очень короткие. Я видел слишком много, где разработчики должны изучить 1001 тайные и субъективные правила, которые демонстрируют знания автора, а не дают полезные советы.

Давайте внимательнее посмотрим …

HTML

В руководстве по стилю HTML есть несколько сюрпризов:

C. Style Guide for C by MIT // Руководство по стилю для C от MIT

  • служить семантическим HTML5 как text / html
  • отдельная разметка, стилизация и скриптинг
  • проверьте вашу разметку, когда это возможно
  • использовать запасные варианты, когда такие технологии, как canvas

Google рекомендует брить каждый байт: файлы должны быть в кодировке UTF-8, завершающий пробел должен быть обрезан, и вы должны избегать ссылок на объекты, таких как и . Они даже рекомендуют опустить дополнительные структуры и закрывающие теги, например

Saving money, saving bytes

Qed.

Uggh. Я все за сохранение нескольких байтов, но все же предпочитаю более строгий XHTML-подобный синтаксис.

Странно, но Google рекомендует делать отступ с двумя пробелами, а не с табуляцией. Разве это не вдвое больше необходимого количества пробельных символов ?!

CSS

В руководящих принципах таблицы стилей преобладают дальнейшие передовые практики и методы сохранения байтов:

  • используйте правильный CSS, если не имеете дело с ошибками или проприетарными синтаксисами (префиксы вендоров)
  • используйте короткие идентификаторы и имена классов, но убедитесь, что они не являются загадочными или презентационными (например, # синяя кнопка)
  • рассмотреть префиксные имена для больших проектов, например # xyz-help, .xyz-column
  • когда это возможно, упростите селекторы, например #example, а не ul # example
  • использовать сокращенные синтаксические обозначения
  • не используйте кавычки в url()
  • используйте короткие #abc шестнадцатеричные обозначения цвета вместо #aabbcc
  • заканчивайте каждое объявление точкой с запятой (даже последней)
  • избегать взломов браузера
Google earth может не запускаться

Google предлагает исключить ведущие нули из измерений, таких как .5em. Это сохраняет символ, но я предпочитаю код, который легче сканировать.

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

Как войти в Engineering Management / Будущее русскоязычного IT-сообщества / Илья Немиро из Wix

Наконец, в нем говорится, что объявления свойств должны быть в алфавитном порядке, например

#example

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

JavaScript

Понятно, что руководство по стилю JavaScript длиннее, но облегчает вам основы:

  • всегда используйте var
  • всегда заканчивать строки точкой с запятой
  • используйте стандартные, а не нестандартные функции
  • используйте константы camelCaseNames и UPPERCASE, но избегайте использования ключевого слова const
  • использовать методы пространства имен
  • избегайте eval()
  • избегать with() for-in
  • использовать массивы и литералы объектов, а не более подробные объявления
  • знать правду и ложные правила
  • не используйте условные комментарии IE в вашем источнике JavaScript
  • не изменяйте прототипы встроенных объектов – это позор, поскольку это одна из более мощных функций JavaScripts, но вы знаете, что это приведет к проблемам
  • используйте замыкания осторожно и не вводите циклические ссылки
  • аналогично, будьте осторожны, используя «это»

Была одна необычная рекомендация: не используйте функции внутри блоков, т.е. напишите:

if (x) < var foo = function() <>>
if (x) < function foo() <>>

Вы увидите второй синтаксис, используемый везде. Это работает без проблем, но это не действительный ECMAScript.

В документе также упоминается, что объекты-обертки никогда не должны использоваться для примитивов, если вы не типизируете. Это может привести к неожиданным результатам, таким как:

var x = new Boolean(false); if (x) < // this code evaluates >

Наконец, в руководстве говорится, что вы должны использовать одинарные кавычки (‘) вместо двойных кавычек (“) при разделении строк, которые могут содержать атрибуты HTML. Я использую двойные кавычки везде, и я не уверен, что смогу легко изменить привычку. Тем не менее, я использую одинарные кавычки для статических строк PHP, так что, возможно, я привередлива!

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

Согласны ли вы с руководствами по стилю Google ? Вынуждает ли ваша компания следовать странным методам разработки?

Источник: coderlessons.com

Руководство по стилю JavaScript от Google: несколько интересных пунктов

Перевод статьи Дэниела Симмонса «Google publishes a JavaScript style guide. Here are some key lessons».

Как подключить Гугл календарь к алисе

Руководство по стилю JavaScript от Google

Для тех, кто еще не в курсе: Google выпустил руководство по стилю кода JavaScript, которое (по мнению Google) должно стать дорожной картой с лучшими стилистическими подходами для написания чистого, понятного кода.

Это не жесткие и неукоснительные правила написания валидного JavaScript-кода. Это скорее рекомендации придерживаться последовательного и приемлемого стиля во всех файлах исходного кода. Это особенно интересно в отношении JavaScript, поскольку это гибкий и “снисходительный” язык, допускающий широкое разнообразие вариантов стиля.

Google и Airbnb выпустили два самых популярных руководства по стилю. Я бы рекомендовал вам просмотреть оба, если вы проводите много времени за написанием кода JS.

Следующие тринадцать пунктов содержат рекомендации, которые я счел самыми интересными в руководстве Google.

Они касаются всего, от вопросов, вызывающих горячие споры (табы и пробелы, обязательность точки с запятой), до нескольких непонятных спецификаций, которые меня удивили. Эти рекомендации определенно изменят мой подход к написанию кода JS в дальнейшем.

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

Используйте пробелы, а не табы

Помимо перевода строки, горизонтальный символ пробела (0x20) ASCII это единственный пробельный символ, используемый в файле исходного кода. Это означает, что символы табуляции не используются для отступов.

Позже в руководстве уточняется, что для создания отступов следует использовать два пробела (не четыре).

// bad function foo() < ∙∙∙∙let name; >// bad function bar() < ∙let name; >// good function baz()

Точки с запятыми обязательны

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

Я не могу представить, почему кто-то противится этой идее, но последовательное использование точек с запятыми в JS становится новым спорным моментом наравне с «пробелами против табов». В этом вопросе Google явно становится на сторону защитников точки с запятой.

// bad let luke = <> let leia = <> [luke, leia].forEach(jedi => jedi.father = ‘vader’) // good let luke = <>; let leia = <>; [luke, leia].forEach((jedi) => < jedi.father = ‘vader’; >);

Пока не используйте модули ES6

Не используйте пока модули ES6 (например, ключевые слова export и import), поскольку их семантика еще не завершена. Имейте в виду, что это правило будет пересмотрено, как только семантика станет полностью стандартизированной.

// Don’t do this kind of thing yet: //—— lib.js —— export function square(x) < return x * x; >export function diag(x, y) < return sqrt(square(x) + square(y)); >//—— main.js —— import < square, diag >from ‘lib’;

Горизонтальное выравнивание не поощряется (но не запрещается)

Эта практика допускается, но в целом не поощряется руководством по стилю от Google. Также не требуется поддерживать горизонтальное выравнивание в тех местах, где оно уже использовалось.

Как поменять основной аккаунт Гугл на телефоне

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

// bad < tiny: 42, longer: 435, >; // good < tiny: 42, longer: 435, >;

Больше не используйте var

Объявляйте все переменные с помощью const или let. По умолчанию используется const, за исключением случаев, кгда нужно переназначить переменную. Ключевое слово var не должно использоваться.

Я все еще вижу, что люди пользуются var в примерах кода на StackOverflow и других сайтах. Не могу сказать, имеет ли это для них большое значение или это просто старая привычка, от которой тяжело избавиться.

// bad var example = 42; // good let example = 42;

Стрелочные функции предпочтительны

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

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

// bad [1, 2, 3].map(function (x) < const y = x + 1; return x * y; >); // good [1, 2, 3].map((x) => < const y = x + 1; return x * y; >);

Используйте строки шаблона вместо конкатенации

Используйте строки шаблона (отделенные с помощью `), а не сложную конкатенацию строк, особенно если задействованы несколько строковых литералов. Строки шаблона могут охватывать несколько строк.

// bad function sayHi(name) < return ‘How are you, ‘ + name + ‘?’; >// bad function sayHi(name) < return [‘How are you, ‘, name, ‘?’].join(); >// bad function sayHi(name) < return `How are you, $< name >?`; > // good function sayHi(name) < return `How are you, $?`; >

Не используйте символов продолжения строки для длинных строк

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

Любопытно, что в отношении этого правила у Google и Airbnb есть разногласия (вот спецификация Airbnb).

В то время как Google рекомендует конкатенацию более длинных строк (как показано внизу), руководство по стилю Airbnb рекомендует ничего не предпринимать и позволять длинным строкам продолжаться так долго, как это необходимо.

// bad (sorry, this doesn’t show up well on mobile) const longString = ‘This is a very long string that far exceeds the 80 column limit. It unfortunately contains long stretches of spaces due to how the continued lines are indented.’; // good const longString = ‘This is a very long string that ‘ + ‘far exceeds the 80 column limit. It does not contain ‘ + ‘long stretches of spaces since the concatenated ‘ + ‘strings are cleaner.’;

Apple мы Google Microsoft или другую

«for… of» предпочтительней, чем цикл for

С ES6 в языке теперь три вида циклов.

Все они могут использоваться, хотя следует отдавать предпочтение циклам for-of, если это возможно.

Как по мне, это странно, но я решил включить этот пункт, поскольку интересен сам факт, что Google отдает предпочтение определенному виду циклов.

Мне всегда казалось, что циклы for. in лучше для объектов, а for. of больше подходят для массивов. Ситуация в стиле «свой инструмент для каждой работы».

Хотя спецификация Google не обязательно противоречит этой идее, все равно интересно знать, что они отдают предпочтение именно этому виду циклов.

Не используйте eval()

Не используйте eval или конструктор Function(…string), особенно для загрузчиков кода. Эти свойства являются потенциально опасными и попросту не работают в CSP-окружениях.

Страница MDN, посвященная eval() , даже содержит раздел под названием «Не используйте eval!».

// bad let obj = < a: 20, b: 30 >; let propName = getPropName(); // returns «a» or «b» eval( ‘var result = obj.’ + propName ); // good let obj = < a: 20, b: 30 >; let propName = getPropName(); // returns «a» or «b» let result = obj[ propName ]; // obj[ «a» ] is the same as obj.a

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

Имена констант используют CONSTANT_CASE: все буквы прописные, слова разделяются символом подчеркивания.

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

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

// bad const number = 5; // good const NUMBER = 5;

Объявляйте переменные по одной

Объявление каждой локальной переменной объявляет только одну переменную: такие объявления, как let a = 1, b = 2; не используются.

// bad let a = 1, b = 2, c = 3; // good let a = 1; let b = 2; let c = 3;

Используйте одинарные, а не двойные кавычки

Обычные строковые литералы ограничиваются одинарной кавычкой (‘), а не двойной («).

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

// bad let directive = «No identification of self or mission.» // bad let saying = ‘Say it ainu0027t so.’; // good let directive = ‘No identification of self or mission.’; // good let saying = `Say it ain’t so`;

Заключительное примечание

Как я говорил в самом начале, это не строгие предписания. Google лишь один из многих технических гигантов и это лишь его рекомендации.

Как сотрудничать с Google

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

Вы можете следовать этим правилам, если хотите иметь «Исходный код, совместимый с Google», а также выбрать из рекомендаций те пункты, с которыми согласны.

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

Источник: techrocks.ru

About this guide

This style guide provides editorial guidelines for writing clear and consistent Google-related developer documentation.

If you’re new to the guide and looking for introductory topics about our style, then start with Highlights, Voice and tone, and Text-formatting summary. Otherwise, use the guide as a reference document for specific questions. For example, you can look up terms in the word list.

Editorial resources

We recommend using the following editorial resources.

Reference hierarchy

Use the following references, including this guide, in this order:

  1. Project-specific style. Follow style guidance specific to your project or product, such as necessary exceptions to this guide or terms that are relevant only to your product.
  2. This style guide. If project-specific style guidelines don’t provide explicit guidance, then follow this guide.
  3. Third-party references. If the preceding references don’t provide explicit guidance, then see these third-party references, depending on the nature of your question:
    Type of questionThird-party reference
    Spelling Follow Merriam-Webster.com. See also Spelling.
    Nontechnical style Follow The Chicago Manual of Style, 17th edition (subscription required).
    Technical style See the Microsoft Writing Style Guide. But consider whether Microsoft’s guidance applies; some of it might apply only to Microsoft products and interfaces.

Other editorial resources

  • Apple Style Guide
  • Red Hat supplementary style guide for product documentation

Annotations used in this guide

For guidance that applies only to Android or Google Cloud documentation, look for the following logos:

  • precedes terms and guidelines specific to Android documentation.
  • precedes terms and guidelines specific to Google Cloud documentation.

Break the rules

Break any of these rules sooner than say anything outright barbarous.

—George Orwell, «Politics and the English Language»

This guide contains guidelines, not rules. Depart from it when doing so improves your content.

Send feedback

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2023-02-08 UTC.

Источник: developers.google.com

Рейтинг
Загрузка ...