Базовый чистый код

Привет, я впервые публикую на Medium :)
Я никогда раньше не писал статей о технологиях. Я обычно пишу художественную литературу. Обожаю, особенно рассказ. Обычно я сначала создаю каркас того, что хочу написать. В нем отражен сюжет повести. Поступая так, я пишу более структурированный рассказ, чтобы читатели поняли.

Когда я инженер-программист, я понимаю, что программирование (кодирование) - это еще и искусство письма. Мы должны писать код, чтобы другие люди (в данном случае другие инженеры-программисты / разработчики) понимали, что мы пишем.

Любой дурак может написать код, понятный компьютеру. Хорошие программисты пишут код, понятный людям.
-Мартин Фаулер, Кент Бек, Джон Брант, Уильям Опдайк и Дон Робертс (1999) Рефакторинг: улучшение дизайна существующего кода. Эддисон-Уэсли.

Итак, здесь я попытался рассказать вам о базовом чистом коде. Поскольку в основном я использую Голанг, образец находится на Голанге. Я думаю, что принцип базового чистого кода одинаков для всех языков программирования.
Отказ от ответственности: это основано на некоторых ссылках и моем опыте.

Зачем нужен чистый код?

1. Люди приходят и уходят
В компании сотрудники приходят и уходят. Мы все еще можем спросить соответствующего разработчика об их коде, когда они все еще работают с нами. Но как только они уйдут, мы должны понять это сами. Кроме того, когда приходят новые люди, они должны выучить код. Что делать, если код запутан?
2. Сотрудничайте с другими
Это относится к пункту № 1. В большинстве случаев мы не меняем код только сами, мы сотрудничаем с другими разработчиками. Помните, что мы работаем с другими. :)
3. Читаемость
Другие разработчики должны легко понять, для чего предназначен наш код. Это означает не только алгоритм, но и название переменной или функции. Важные простые вещи.
4. Модульность
Создаваемая нами функция должна быть модульной, чтобы ее можно было повторно использовать другой функцией.

Что следует учитывать при написании чистого кода

1. Последовательность импорта библиотек (пакетов)
Во-первых, мы обычно не пишем только в 1 файл. Во-вторых, иногда нам нужны функции из репозитория других людей или даже из пакета нашего собственного репозитория.
Если мы импортируем много библиотек / пакетов, которые находятся в неправильном порядке, это вызовет беспорядок в нашем коде. Нам лучше определить последовательность импорта библиотек (пакетов).
Например, последовательность:

- Golang library
- Controller package from our own repository
- Model package from our own repository
- Other package from our own repository, like util or common package
- Third party repository

Это зависит от ваших предпочтений, но обычно предпочтение отдается последней стороне.
2. Значимое имя

2.1 Имя переменной
Используйте четкое существительное, чтобы другие поняли, что это такое. Например:
- Одна переменная.

- Переменная при зацикливании
Обычно мы легко находим что-то вроде:

Что такое «я»? Что такое j?
Может быть, тогда мы вспомнили, что это такое. Но, спустя несколько месяцев, кто знает?
Нам нужно перечитать код на случай, если мы его забудем. Так что не делай этого.

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

Например:

- Название структуры

Людям будет интересно. Что такое «данные»?
Какие данные вы имеете в виду? Можете ли вы представить, если существует более 10 структур с именем «данные»?

Итак, это очевидно. Судя по названию, люди все поймут.

2.2 Название параметров

Может быть, это нормально, но давайте представим, когда у него более 1 параметра.

2.3 Название функции

Какова цель функции? Что делает функция? «Получить», не так ли? «Сет», не так ли?

Используйте clear глагол для имени функции. Таким образом, другие разработчики легко поймут, что он делает, только прочитав имя функции.

2.4 Постоянная

Может быть, эта функция все еще хороша, если функция все еще небольшая и небольшая.

Для статического значения лучше использовать константу.

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

- Маленький
Функция должна быть маленькой, иметь определенную цель. Если у него много задач, лучше провести рефакторинг.
- Многоразовый
Чистый код не содержит повторяющегося кода. Если функция уже выполняет определенную задачу, мы можем повторно использовать ее в другой функции.
- Общие параметры
Если общее количество параметров больше 3 или 4, мы должны проверить это, если он выполняет много задач или если несколько алгоритмов объединены в одну функцию.
В SonarQube рекомендуется использовать не более 4 параметров.

4. Комментарии
Наилучшие комментарии - те, в которых вы не нуждаетесь. Но разве комментировать код - это плохо? Нет. Это зависит от потребностей.

Код говорит вам, как, комментарии говорят вам, почему.

Когда оставлять комментарии?
- Юридические комментарии

// Copyright 2014 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the “License”);
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0

- Информативные комментарии

// Supported format: yyyy-mm-dd hh:mm:ss

- Сложная логика
Нужны комментарии, чтобы понять, что делает этот сложный алгоритм.

// This will get x data, compare with in y data.
// Then, it will do…

Когда нельзя комментировать?
- Глупые комментарии

- Комментарий к очевидной функции
Избыточная информация. Не нужно этого делать:

// This function is to insert user
func InsertUser(){}

Дополнительные вещи

Ниже основано на том, что я делал, работая инженером-программистом.
1. Зафиксировать

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

Messy one:
Fix bug

Какая ошибка? Что вы исправляете?

Better one:
Improvement on x when y by using z

Подробно опишите, что вы пытаетесь изменить.

2. Модульный тест
И последнее, но не менее важное: не забудьте пройти модульный тест! Он должен пройти все испытания. Важно убедиться, что созданная нами функция работает так, как мы ожидали.

Вы можете узнать больше о модульном тесте на:

Https://medium.com/@erhemdiputra/how-to-write-unit-test-in-golang-8ebdbfb7cf80

Заключение

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

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

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

Подробнее

Https://rules.sonarsource.com/typescript/RSPEC-107
http://slides.com/hamdiahmadi/deck-4bf133f4-2aeb-4cea-9435-3501cf0a971f#/5/2

Пожалуйста, оставьте любые комментарии или предложения. Спасибо :)