Облегчение жизни за счет написания легко читаемого кода

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

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

Действительно ли нам нужны комментарии?

Возникал ли у вас когда-нибудь этот вопрос? Если да, отлично. Надеюсь, вы уже нашли ответ. Если нет, ничего страшного, отвечу. У нас уже есть правильное именование всего на месте. Так что наш код уже стал более читабельным. Тогда действительно ли нам нужны еще комментарии? Я говорю это, потому что пока все, что я узнал, было то, что комментарии используются, чтобы рассказать о том, что происходит, и помочь читателю получить представление о том, что делается. И я считаю, что большинство из нас питаются только такими знаниями. В качестве примера мы просто добавляем такие комментарии, как:

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

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

Комментарии действительно имеют какое-то значение, и они созданы для определенной цели. Есть места, которые можно заполнить только с помощью комментариев. Давайте обсудим эти ситуации более подробно.

/ * избегать комментариев * /

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

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

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

Еще один плохой способ использования комментариев в коде - использование комментариев в качестве разделителя для разделения различных частей кода. Мы делаем это, думая, что это делает наш код более привлекательным. Но на самом деле это не так.

Я оставил худшее напоследок. Большинство из нас делает это не один раз, а много раз.

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

/ * добавьте сюда комментарии * /

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

# Copyright 2016 The TensorFlow Authors. All Rights Reserved.
#
# 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
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
# ==================================================================

Приведенный выше код взят со страницы TensorFlow Github. Это пример использования комментариев для отображения информации о лицензии. Так что в этой ситуации можно использовать комментарии.

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

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

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

Добавлять заметки «Todo» тоже можно, но не переусердствуйте.

Хотя лучше реализовывать функции полностью или поэтапно без комментариев «Todo», оставлять несколько комментариев «Todo» здесь и там не повредит, особенно потому, что современные IDE позволяют легко находить эти заметки.

Тем не менее, нет никакой пользы для читабельности вашего кода (или вашего общего качества кода), если вы оставите повсюду кучу комментариев «Todo»!

Форматирование кода

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

Мы увидим два вида форматирования - вертикальное и горизонтальное форматирование кода.

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

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

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

При добавлении пустых строк следует помнить о двух концепциях.
Плотность по вертикали. Связанные понятия / коды следует размещать рядом друг с другом.
Расстояние по вертикали: Не связанные между собой понятия следует разделять.

Здесь у нас есть две основные концепции в функции регистрации: проверка и создание нового пользователя в базе данных. Таким образом, эти два понятия следует разделять пустой строкой. Напротив, создание пользовательского объекта и последующий вызов saveToDatabase () для него принадлежат друг другу, поэтому между ними не должно быть пустых строк.

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

Функции и методы заказа

Когда дело доходит до упорядочивания функций и методов, рекомендуется следовать «правилу понижения».

Функция validate (), которая вызывается функцией login (), должна быть (близко) ниже функции login (), чтобы обеспечить большую вертикальную плотность.

Разделение кода между файлами

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

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

Разбиение длинных строк на несколько строк

Не используйте слишком длинные строки кода и не усложняйте понимание и понимание, даже если это простая функция.

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

Приведенный выше фрагмент выполняет ту же логику, но его легче читать.

Использование коротких имен

Имена должны быть описательными - вы это уже узнали. Но не следует тратить место и усложнять чтение из-за излишней конкретности. Рассмотрим это имя:

loggedInUserAuthenticatedByEmailAndPassword = …

Это слишком конкретно! loggedInUser будет достаточно!

Ключевые выводы:

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

Я надеюсь, что вы нашли эту статью полезной и познакомили вас со стилем программирования, которому вы следуете. Спасибо, что прочитали это, и не забудьте добавить свои / * комментарии * / к этому сообщению.

Присоединяйтесь к FAUN: Веб-сайт 💻 | Подкаст 🎙️ | Twitter 🐦 | Facebook 👥 | Instagram 📷 | Группа Facebook 🗣️ | Группа Linkedin 💬 | Slack 📱 | Cloud Native Новости 📰 | Еще .

Если этот пост был полезен, нажмите несколько раз кнопку хлопка 👏 ниже, чтобы выразить поддержку автору 👇