Fix images

1 files changed, 67 insertions, 74 deletions

diff --git a/content/pages/gostyleguide/google/guide.md b/content/pages/gostyleguide/google/guide.md
index 31b3b33..e22a8aa 100644
--- a/content/pages/gostyleguide/google/guide.md
+++ b/content/pages/gostyleguide/google/guide.md
@@ -1,16 +1,12 @@
 ---
-order: 3
-title: Google Go Style Guide — Руководство
+weight: 10
+title: Руководство по стилю Go
 ---
 
 # Руководство по стилю Go (Go Style Guide)
 
 Оригинал: https://google.github.io/styleguide/go/guide
 
-[Обзор](https://neonxp.ru/pages/gostyleguide/google/) | [Руководство](https://neonxp.ru/pages/gostyleguide/google/guide) | [Решения](https://neonxp.ru/pages/gostyleguide/google/decisions) |
-[Лучшие практики](https://neonxp.ru/pages/gostyleguide/google/best-practices)
-
-
 **Примечание:** Это часть серии документов, описывающих [Стиль Go (Go
 Style)](https://neonxp.ru/pages/gostyleguide/google/) в Google. Данный документ является **[нормативным
 (normative)](https://neonxp.ru/pages/gostyleguide/google/#normative) и [каноническим (canonical)](https://neonxp.ru/pages/gostyleguide/google/#canonical)**.
@@ -52,8 +48,8 @@ Style)](https://neonxp.ru/pages/gostyleguide/google/) в Google. Данный д
 Важнее, чтобы код был легок для чтения, а не для написания. Понятность кода
 имеет два аспекта:
 
-*   [Что именно делает код?](#clarity-purpose)
-*   [Почему код делает то, что он делает?](#clarity-rationale)
+- [Что именно делает код?](#clarity-purpose)
+- [Почему код делает то, что он делает?](#clarity-rationale)
 
 <a id="clarity-purpose"></a>
 
@@ -64,10 +60,10 @@ Go разработан таким образом, чтобы относител
 предварительные знания для понимания кода, стоит потратить время, чтобы сделать
 цель кода более ясной для будущих читателей. Например, может помочь:
 
-*   Использование более описательных имен переменных
-*   Добавление дополнительных комментариев
-*   Разделение кода пробелами и комментариями
-*   Рефакторинг кода в отдельные функции/методы для повышения модульности
+- Использование более описательных имен переменных
+- Добавление дополнительных комментариев
+- Разделение кода пробелами и комментариями
+- Рефакторинг кода в отдельные функции/методы для повышения модульности
 
 Здесь нет универсального решения, но при разработке кода на Go важно отдавать
 приоритет понятности.
@@ -81,10 +77,10 @@ Go разработан таким образом, чтобы относител
 особенно важно, когда код содержит нюансы, с которыми читатель может быть не
 знаком, например:
 
-*   Нюанс языка, например, замыкание захватит переменную цикла, но само
-    замыкание находится далеко от него
-*   Нюанс бизнес-логики, например, проверка прав доступа, которая должна
-    различать реального пользователя и того, кто выдает себя за пользователя
+- Нюанс языка, например, замыкание захватит переменную цикла, но само
+  замыкание находится далеко от него
+- Нюанс бизнес-логики, например, проверка прав доступа, которая должна
+  различать реального пользователя и того, кто выдает себя за пользователя
 
 API может требовать осторожного использования. Например, фрагмент кода может
 быть сложным и трудным для понимания из-за соображений производительности, или
@@ -99,8 +95,8 @@ API может требовать осторожного использован�
 беспорядок, пересказывая то, что код уже говорит, противореча коду или добавляя
 нагрузку по поддержке актуальности комментариев. Позвольте коду говорить самому
 за себя (например, делая имена символов самодокументированными), а не добавляйте
-избыточные комментарии. Зачастую лучше, чтобы комментарии объясняли, *почему*
-что-то сделано, а не *что* делает код.
+избыточные комментарии. Зачастую лучше, чтобы комментарии объясняли, _почему_
+что-то сделано, а не _что_ делает код.
 
 Кодовая база Google в значительной степени единообразна и согласована. Часто
 бывает, что код, который выделяется (например, использованием незнакомого
@@ -111,16 +107,16 @@ API может требовать осторожного использован�
 Стандартная библиотека содержит множество примеров реализации этого принципа.
 Среди них:
 
-*   Комментарии сопровождающих в [`package
-    sort`](https://cs.opensource.google/go/go/+/refs/tags/go1.19.2:src/sort/sort.go).
-*   Хорошие [запускаемые примеры в том же
-    пакете](https://cs.opensource.google/go/go/+/refs/tags/go1.19.2:src/sort/example_search_test.go),
-    которые полезны как пользователям (они [отображаются в
-    godoc](https://pkg.go.dev/sort#pkg-examples)), так и сопровождающим (они
-    [запускаются как часть тестов](https://neonxp.ru/pages/gostyleguide/google/decisions/#examples)).
-*   [`strings.Cut`](https://pkg.go.dev/strings#Cut) — это всего четыре строки
-    кода, но они повышают [понятность и корректность мест вызова
-    (callsites)](https://github.com/golang/go/issues/46336).
+- Комментарии сопровождающих в [`package
+sort`](https://cs.opensource.google/go/go/+/refs/tags/go1.19.2:src/sort/sort.go).
+- Хорошие [запускаемые примеры в том же
+  пакете](https://cs.opensource.google/go/go/+/refs/tags/go1.19.2:src/sort/example_search_test.go),
+  которые полезны как пользователям (они [отображаются в
+  godoc](https://pkg.go.dev/sort#pkg-examples)), так и сопровождающим (они
+  [запускаются как часть тестов](https://neonxp.ru/pages/gostyleguide/google/decisions/#examples)).
+- [`strings.Cut`](https://pkg.go.dev/strings#Cut) — это всего четыре строки
+  кода, но они повышают [понятность и корректность мест вызова
+  (callsites)](https://github.com/golang/go/issues/46336).
 
 <a id="simplicity"></a>
 
@@ -133,17 +129,17 @@ API может требовать осторожного использован�
 как с точки зрения поведения, так и производительности. Внутри кодовой базы Go в
 Google простой код:
 
-*   Легко читается сверху вниз
-*   Не предполагает, что вы уже знаете, что он делает
-*   Не предполагает, что вы можете запомнить весь предшествующий код
-*   Не имеет ненужных уровней абстракции
-*   Не имеет имен, которые привлекают внимание к чему-то обыденному
-*   Делает передачу значений и принятие решений понятными для читателя
-*   Имеет комментарии, которые объясняют *почему*, а не *что* делает код, чтобы
-    избежать будущих отклонений
-*   Имеет самодостаточную документацию
-*   Имеет полезные ошибки и полезные сообщения об ошибках в тестах
-*   Часто может быть взаимоисключающим с "умным" кодом
+- Легко читается сверху вниз
+- Не предполагает, что вы уже знаете, что он делает
+- Не предполагает, что вы можете запомнить весь предшествующий код
+- Не имеет ненужных уровней абстракции
+- Не имеет имен, которые привлекают внимание к чему-то обыденному
+- Делает передачу значений и принятие решений понятными для читателя
+- Имеет комментарии, которые объясняют _почему_, а не _что_ делает код, чтобы
+  избежать будущих отклонений
+- Имеет самодостаточную документацию
+- Имеет полезные ошибки и полезные сообщения об ошибках в тестах
+- Часто может быть взаимоисключающим с "умным" кодом
 
 Могут возникать компромиссы между простотой кода и простотой использования API.
 Например, может иметь смысл сделать код более сложным, чтобы конечному
@@ -219,11 +215,11 @@ Google простой код:
 
 Многое может помешать выделению наиболее важных деталей в любой момент:
 
-*   Повторяющийся код
-*   Лишний синтаксис
-*   [Непонятные имена](#naming)
-*   Ненужная абстракция
-*   Пробелы
+- Повторяющийся код
+- Лишний синтаксис
+- [Непонятные имена](#naming)
+- Ненужная абстракция
+- Пробелы
 
 Повторяющийся код особенно затмевает различия между каждым почти идентичным
 разделом и требует от читателя визуального сравнения похожих строк кода, чтобы
@@ -258,8 +254,7 @@ if err := doSomething(); err == nil { // если ошибки НЕТ
 }
 ```
 
-[Табличное тестирование (Table-driven testing)]:
-    https://github.com/golang/go/wiki/TableDrivenTests
+[Табличное тестирование (Table-driven testing)]: https://github.com/golang/go/wiki/TableDrivenTests
 [обработке ошибок (error handling)]: https://go.dev/blog/errors-are-values
 ["усилить" сигнал]: best-practices#signal-boost
 
@@ -273,15 +268,15 @@ if err := doSomething(); err == nil { // если ошибки НЕТ
 
 Поддерживаемый код:
 
-*   Легко модифицируется будущим программистом правильно
-*   Имеет API, структурированные таким образом, что они могут элегантно
-    развиваться
-*   Четко указывает предположения, которые он делает, и выбирает абстракции,
-    которые соответствуют структуре проблемы, а не структуре кода
-*   Избегает ненужной связности и не включает неиспользуемые функции
-*   Имеет комплексный набор тестов, чтобы гарантировать сохранение заявленного
-    поведения и корректность важной логики, а тесты предоставляют четкие,
-    действенные диагностические сообщения в случае неудачи
+- Легко модифицируется будущим программистом правильно
+- Имеет API, структурированные таким образом, что они могут элегантно
+  развиваться
+- Четко указывает предположения, которые он делает, и выбирает абстракции,
+  которые соответствуют структуре проблемы, а не структуре кода
+- Избегает ненужной связности и не включает неиспользуемые функции
+- Имеет комплексный набор тестов, чтобы гарантировать сохранение заявленного
+  поведения и корректность важной логики, а тесты предоставляют четкие,
+  действенные диагностические сообщения в случае неудачи
 
 При использовании абстракций, таких как интерфейсы и типы, которые по
 определению удаляют информацию из контекста, в котором они используются, важно
@@ -397,12 +392,11 @@ leap := leap4 && (!leap100 || leap400)
 
 Все исходные файлы Go должны соответствовать формату, выводимому инструментом
 `gofmt`. Этот формат обеспечивается проверкой перед отправкой (presubmit check)
-в кодовой базе Google.  [Сгенерированный код] также обычно должен
+в кодовой базе Google. [Сгенерированный код] также обычно должен
 форматироваться (например, с использованием [`format.Source`]), так как он также
 просматривается в Code Search.
 
-[Сгенерированный код]:
-    https://docs.bazel.build/versions/main/be/general.html#genrule
+[Сгенерированный код]: https://docs.bazel.build/versions/main/be/general.html#genrule
 [`format.Source`]: https://pkg.go.dev/go/format#Source
 
 <a id="mixed-caps"></a>
@@ -436,11 +430,11 @@ case) вместо подчеркиваний (змеиный регистр, sn
 
 Не разделяйте строку:
 
-*   Перед [изменением отступа (indentation
-    change)](https://neonxp.ru/pages/gostyleguide/google/decisions/#indentation-confusion) (например, объявление функции,
-    условие)
-*   Чтобы длинная строка (например, URL) поместилась в несколько более коротких
-    строк
+- Перед [изменением отступа (indentation
+  change)](https://neonxp.ru/pages/gostyleguide/google/decisions/#indentation-confusion) (например, объявление функции,
+  условие)
+- Чтобы длинная строка (например, URL) поместилась в несколько более коротких
+  строк
 
 <a id="naming"></a>
 
@@ -450,16 +444,15 @@ case) вместо подчеркиваний (змеиный регистр, sn
 короче, чем во многих других языках, но применяются те же [общие принципы].
 Имена должны:
 
-*   Не казаться [избыточными (repetitive)](https://neonxp.ru/pages/gostyleguide/google/decisions/#repetition) при
-    использовании
-*   Учитывать контекст
-*   Не повторять концепции, которые уже ясны
+- Не казаться [избыточными (repetitive)](https://neonxp.ru/pages/gostyleguide/google/decisions/#repetition) при
+  использовании
+- Учитывать контекст
+- Не повторять концепции, которые уже ясны
 
 Более конкретные рекомендации по именованию можно найти в [решениях
 (https://neonxp.ru/pages/gostyleguide/google/decisions/)](https://neonxp.ru/pages/gostyleguide/google/decisions/#naming).
 
-[общие принципы]:
-    https://testing.googleblog.com/2017/10/code-health-identifiernamingpostforworl.html
+[общие принципы]: https://testing.googleblog.com/2017/10/code-health-identifiernamingpostforworl.html
 
 <a id="local-consistency"></a>
 
@@ -473,13 +466,13 @@ case) вместо подчеркиваний (змеиный регистр, sn
 
 Примеры **допустимых** соображений локального стиля:
 
-*   Использование `%s` или `%v` для форматированного вывода ошибок
-*   Использование буферизованных каналов вместо мьютексов
+- Использование `%s` или `%v` для форматированного вывода ошибок
+- Использование буферизованных каналов вместо мьютексов
 
 Примеры **недопустимых** соображений локального стиля:
 
-*   Ограничения на длину строк для кода
-*   Использование библиотек тестирования на основе утверждений (assertion-based)
+- Ограничения на длину строк для кода
+- Использование библиотек тестирования на основе утверждений (assertion-based)
 
 Если локальный стиль противоречит руководству по стилю, но влияние на читаемость
 ограничено одним файлом, это обычно будет отмечено в ревью кода, для которого
@@ -492,4 +485,4 @@ case) вместо подчеркиваний (змеиный регистр, sn
 допустимым обоснованием для нарушения руководства по стилю в новом коде. В этих
 случаях автору уместно либо очистить существующую кодовую базу в том же CL, либо
 выполнить рефакторинг перед текущим CL, либо найти альтернативу, которая, по
-крайней мере, не усугубляет локальную проблему.
\ No newline at end of file
+крайней мере, не усугубляет локальную проблему.