Запись от Кристиана Ковача, консультанта Adaptavist.

Добро пожаловать во вторую публикацию из серии блогов Gotta Script-em All, в которой мы изучаем возможности Jira с помощью пошагового руководства по созданию бесшовных интеграционных связей между Jira и другими инструментами. .

В Части 1 мы рассмотрели, как создать пользовательскую кнопку и конечную точку отдыха в пользовательском интерфейсе Jira. В этом посте мы возвращаемся к основам с руководством по написанию чистого кода. Мы объясним, почему важно писать код так, чтобы любой мог понять его с первого раза.

Итак, давайте начнем с того, почему так важно писать чистый код.

Одним из лучших руководств по этой теме, которые я читал, является метко названный Чистый код. Автор, отраслевой эксперт, Robert C Martin предлагает следующее:

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

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

Чтобы преуспеть в написании чистого кода, вы должны написать его так, чтобы и машины, и люди могли его интерпретировать и понимать в течение многих лет.

1. Сделайте ваш код читабельным

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

В начале своей карьеры я писал код одним большим куском. Я использовал такие значения, как a, b, tsm, smb и т. д. Хотя в то время использование этих значений имело смысл, перенесемся на несколько недель вперед, и я понятия не имел, что имел в виду под 'тсм'.

Если я не мог вспомнить свой код, как мог кто-то другой?

Чтобы напомнить мне о том, что я написал и почему я это написал, я вскоре понял, что мне нужно сделать мой код читабельным, поэтому мое значение 'tsm' стало 'timeSettingManager' и так далее.

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

2. Сделайте свой код многоразовым

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

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

Вот пример миньона кода в действии:

static getCustomField(Issue issue, String customFieldID) {
return issue.getCustomFieldValue(ComponentAccessor.getCustomFieldManager()
.getCustomFieldObject(customFieldID))
}

И вот как я могу сослаться на это:

CustomField myLittleCustomField = getCustomField(anIssue, "customfieldid")

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

3. Сделайте свой код простым в использовании и делитесь им

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

//------------------------------------------------------------------
// This script will display a warning message if the date is between
// the start and end date of the issues filtered by the given query.
// The script is universal in the sense that it can be added to any
// date field and will display the warning under it (in the description).
//------------------------------------------------------------------
// Please change the following so the script would suit your needs:
String changeFreezeStartDateField   = "customfield_10300"
String changeFreezeEndDateField     = "customfield_10301"
String jiraAdmin                    = "admin"
String filterQuery                  = "Freeze Period"
String fieldNameOnScreen            = "Change Start Date / Time"
//------------------------------------------------------------------

Таким образом, вместо того, чтобы клиенту приходилось изменять код в строках 12, 187, 299, 305 и т. д., он может внести любые необходимые изменения в заголовок.

4. Сделайте свой код удобным для просмотра

Я обычно создаю свой код в портретном режиме, используя монитор Full HD (High Definition), что означает, что вместо разрешения 1920x1080 оно составляет 1080x1920.

Люди используют разные компьютеры, устройства и мониторы для просмотра кода, поэтому, чтобы избежать каких-либо разрывов кода на небольших экранах, очень важно, чтобы длина строк кода не превышала 80 символов. Следование этому правилу особенно полезно, когда я проверяю свой код на наличие ошибок или проблем с помощью «демонстрации экрана» на клиентских компьютерах.

Поскольку мы часто тратим больше времени на чтение кода, чем на его написание, использование правильных соглашений об именах для вашего кода сделает вашу жизнь проще. Используя чистые соглашения об именах кода (длинные описательные имена), я могу хранить свои открытия в своем коде. Например, однажды я придумал, как из Jira извлекать конкретные даты:

Date getFieldDate( String fieldName) {
def formField = getFieldByName(fieldName)
String stringDate = formField.getValue()
Date date = new Date().parse("EEE MMM dd kk:mm:ss z yyyy", stringDate)
return date
}

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

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

if (issue.created == getFieldDate("Start Date")) dostuff...

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

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

5. Сделайте структуру кода последовательной

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

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

Каждый фрагмент кода, который я пишу, имеет одну и ту же структуру:

import com.stuff.text.something
import com.atlassian.more.stuff
//------------------------------------------------------------------
// This a brief explanation of the script and instructions about
// how to use it.
//------------------------------------------------------------------
String myLittleGlobalVariable = "change this value"
String anotherGlobalVariable = "user of the script must change it"
//------------------------------------------------------------------
static doSomethingLittle(String localVariableWithProperName) {
//I often use the global variables' value channeled into my local variable.
return someData
}
static getSomeDataFromJira (String localVariableWithProperName) {
//This piece does one tiny thing and nothing else.
}
String catchReturnedData = doSomethingLittle(myLittleGlobalVariable)
write.onScreen(getSomeDataFromJira(catchReturnedData)

Чистота - залог здоровья

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

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

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

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

Об авторе:

Кристиан (Крис) Ковач — консультант Адаптавист, с опытом системного администрирования, обеспечения качества (QA) (ручные и автоматические тесты), ScriptRunner и настройка продуктов Atlassian. Он обладает знаниями и опытом работы с различными языками программирования, включая JAVA, HTML, CSS, Pascal и C#.

Первоначально опубликовано на www.adaptavist.com.