Вы, вероятно, читаете это по двум причинам. Во-первых, вы OutSystems-разработчик. Во-вторых, вы хотите стать лучшим разработчиком OutSystems. Это хорошо, нам нужны лучшие OutSystems-разработчики!
В этом блоге я расскажу о чистом коде, значимых именах, комментариях и действиях.
1. Введение
Не буду говорить вам, что разработка - это весело, но и сложно. Пользователи требуют новых функций быстрее, чем когда-либо, и требуют еще более сложной логики.
OutSystems - это платформа с низким кодом. OutSystems снимает с нас большую нагрузку и направляет вас к решению бизнес-задач вместо создания классов. TrueChange (tm) предотвратит создание очевидных ошибок. Таким образом, нам не нужно беспокоиться о чистом коде, верно?
Неправильный! Даже с low-code правила чистого кода так или иначе применяются. В OutSystems по-прежнему легко создавать ненужные зависимости. Повторяющиеся действия, странные комментарии и неоднозначное именование.
Когда у вас есть плохой код в системе, он вырастет до еще более плохого кода, потому что разработчики боятся его менять. Возможно, они доверяют ему и будут развивать код в дальнейшем или даже создадут дублированный экшен, который будет делать то же самое, но немного по-другому.
Внезапно вы замечаете, что количество ошибок увеличивается, а количество новых функций уменьшается.
2. Текущий инструментарий
У нас есть лучшие практики для согласованности, соглашений об именах и сохранения модулей меньше 4 МБ. У нас даже есть такие инструменты, как Discovery или Clean Architecture Tool для проверки глобальной архитектуры. Наконец, у нас есть такие инструменты, как Tosca и Selenium, для тестирования конечных пользователей. В ближайшее время появятся такие инструменты, как Boncode, чтобы проверить, нет ли у нас дублированного кода и не слишком ли большие функции.
Тем не менее, мы, как разработчики, можем сделать даже больше сами, чтобы создать чистый код и код, поддерживаемый в сопровождении. Все для счастливых разработчиков, пользователей и DevOps. Мы не должны полагаться на тестировщиков в поиске ошибок. Мы должны для начала убедиться в отсутствии ошибок.
Как это сделать, ну ...
3. А вот и чистый код.
Роберт С. Мартин написал несколько книг о чистом кодировании, которые могут помочь вам лучше писать чистый код и помочь вам преобразовать плохой код в хороший. Это требует большей дисциплины от нас, разработчиков, а также, вероятно, означает, что у нас будет более низкая скорость в наших спринтах.
Тем не менее, лучше писать отличный и поддерживаемый код, чем быстрый код, который вводит плохой код.
Я расскажу о некоторых концепциях, описанных Мартином в своей книге, и спроецирую их на то, как, по моему мнению, мы должны использовать и применять их в OutSystems. Для меня это тоже исследование, так как я действительно хочу улучшить каждый проект, в котором я принимаю участие, поэтому, пожалуйста, присоединяйтесь ко мне в обсуждениях на эту тему.
4. Оставьте палаточный лагерь более чистым, чем вы его нашли.
Это Правило бойскаута, которое вы также должны применять здесь. Если есть одна вещь, которую вы всегда должны делать при исправлении ошибок или разработке новых экранов, - это делать ее лучше, чем было раньше. Это простое правило может значительно облегчить жизнь. Но это работает только тогда, когда у вас в первую очередь хорошее тестовое покрытие, что довольно сложно сделать в OutSystems. Я рекомендую попробовать иметь полный набор тестов для вашего кода.
5. Значимые имена
У OutSystems действительно есть некоторые лучшие практики в отношении соглашений об именах.
- Значимые имена (например, «Клиент» вместо «Cstr»).
- Используйте PascalCase (например, IsCustomerValid, FetchCookies)
- Суффикс внешних ключей с «Id» (например, «CustomerId»)
- Включите название организации в название записи (например, «клиент» вместо «запись»)
- Группировать экраны с префиксом (например, «Customer_Edit», «Customer_Show»)
- Префикс действий, вызываемых таймерами, с помощью «Timer_»
- Установите свойство Name для ShowRecords, EditRecords и TableRecords
Помогает ли это нам создавать значимые имена?
Используйте имена, раскрывающие намерение
Я знаю, что он делает, а ты? Я предполагаю, что вы поняли идею, увидев имя и увидев, что оно получает что-то из базы данных, прокрутите его, если возможно, и что-то сделаете с Результатом. Этот фрагмент кода соответствует требованиям Best Practice, однако что-то не так.
Поразмыслив, изменив, вернувшись назад, я прихожу к следующим изменениям в этом действии.
Как видите, я переименовал действие, чтобы представить, что оно делает, оно возвращает UnselectedApplicationIds, что более значимо, чем GetIgnoredApps, потому что на самом деле оно возвращает только список идентификаторов. Также есть некоторая очистка самого действия без изменения конечного результата.
Как разработчик, мы не должны легкомысленно думать о том, как мы называем наши действия и переменные. Они должны быть значимыми и легко различимыми, в чем заключается цель этого конкретного действия или переменной.
Избегайте дезинформации
Это относительно просто, и мы должны избегать имен, которые не говорят о том, что они на самом деле делают. Например, когда вы возвращаете одно приложение вместо нескольких приложений, имя, конечно же, не должно быть ApplicationList.
В моем коде я также заметил действие под названием «DeleteTables».
Ой, намерение вполне понятно! К сожалению, он удаляет только содержимое двух таблиц (возможно, с некоторым каскадом, но не все таблицы, которые у меня есть). Теперь мне придется вернуться к тому, когда он действительно был вызван и почему, чтобы я мог переименовать его в лучший, чтобы он действительно раскрыл цель этого действия.
Делайте значимые различия
По моему опыту, это самый сложный орешек с точки зрения именования. Как часто мы получаем пару действий, которые выглядят так
Как мы узнаем, какое действие выбрать в каком случае, в чем различия?
Кроме того, старайтесь избегать таких имен, как «edgeJSON», потому что, даже если мы знаем намерение, что, если мы решим изменить его на XML? То же самое и с такими именами, как «NameString» или «RecordAccount», поскольку они предоставляют информацию, которую можно изменить позже. Запись может быть изменена на структуру, будет ли она по-прежнему записью, или ее нужно будет изменить на «StructureAccount»?
Избегайте кодировок
OutSystems строго типизирован, поэтому использовать Венгерскую нотацию (например, iSize) нецелесообразно. Как разработчик, мы должны думать об этом, когда хотим решить проблему.
Выберите одно слово для каждой концепции
Выберите одно слово для каждого абстрактного понятия и придерживайтесь его. Например, довольно сбивает с толку видеть в коде «get», «fetch», «retrieve». Причина, по которой он появляется в коде, обычно является привычкой самого разработчика. Возможно, мы сталкиваемся с проблемой с различиями и не можем лучше назвать действие. К счастью, это легко исправить с помощью простого поиска и замены.
Заключение
Именование сложно, и к нему нельзя относиться легкомысленно. Немного сложнее то, что OutSystems ограничивает длину действий, структур и имен переменных, что способствует сокращенному и загадочному именованию. Так что, если вы заботитесь о хорошем чистом коде, пожалуйста, поддержите идею удлинения имен.
6. Комментарии
Комментарии - это необходимое зло для начала. Они сложны и «устаревают», если вы не позаботитесь о них. Есть хорошие комментарии и плохие комментарии. Опасность хороших комментариев в том, что со временем они могут превратиться в плохие комментарии. К сожалению, плохие комментарии никогда не превратятся в хорошие!
Информативные комментарии
Комментарии могут быть полезны, чтобы увидеть, какова цель логики (или когда присвоения имен недостаточно из-за природы OutSystems).
Будьте осторожны, чтобы не заменить собственное имя действия, потому что было бы лучше изменить действие или реорганизовать его лучше.
TODO комментарии
Да, это отличная возможность помочь разработчикам. Однако их следует каждый раз пересматривать, потому что в конечном итоге их нужно сделать и избавиться от них!
Избыточные комментарии
Не делайте этого, это бессмысленно и только загромождает экран.
Бормочет и т. Д.
Это помогает?
Закомментированные действия
Хорошо, теперь мне нужно быть осторожным. У нас НЕ было этого до P11, но некий человек (его имя известно!) Решил, что это отличная идея, и предложил это как таковое. Итак, теперь у нас есть эта функция в P11.
Будьте очень осторожны, у нас все равно есть версии, поэтому не перетаскивайте закомментированные действия слишком долго. Лучше поместить их в модули, предназначенные только для разработчиков, вместо того, чтобы возвращать их в производственный код!
Комментарии журнала
Пока мы не получим какие-то комментарии к публикации, мы как бы застряли с такими комментариями в OutSystems. Я настоятельно рекомендую не использовать их ни в коем случае, потому что не очень информативно то, что Джон Доу добавил логическое значение в 2015 году в ActionY.
Заключение
Как однажды сказал один знаменитый рыцарь: «Но выбирайте с умом, потому что, хотя истинный Комментарий принесет вам информацию, ложный Комментарий заберет ее у вас».
7. Действия
В OutSystems мы везде используем действия. И вы можете создавать красивые чистые действия или действия, которые могут оказаться сложными, не обслуживаемыми и вызывать странные побочные эффекты. Например, попытка решить проблему в одном месте приводит к тому, что в другом месте все падает, как хорошая игра jenga. Здесь я говорю в основном о действиях сервера и действиях служб, действия на экране могут немного отличаться.
Небольшой
Действия должны быть небольшими, и если у вас есть возможность, сделайте их еще меньше. Когда действия небольшие, вы легко можете понять, что они делают и почему. Для них также проще сделать тестовые наборы. Возьмите этот образец
Для меня это слишком большое действие, и я думаю, что его нужно реорганизовать, чтобы прояснить, что оно делает, не думая о самом потоке.
Другой пример показывает, что делает действие гораздо проще.
Я обычно стремлюсь иметь максимум десять узлов между началом и концом, исключая простые боковые стороны и обработчики исключений. Однако команда также должна решить, что они сочтут пригодным для использования.
Сделай одно дело
Действия должны делать одно. Они должны делать это хорошо, они должны только это делать.
Проще говоря, но сделать это сложно. Чтобы не делать что-то дважды, нам нравится думать о том, чтобы делать несколько вещей одновременно. Однако это может быть непросто. Что, если ты больше не хочешь заниматься этим другим? Если вы закодируете его «правильно», то придется удалить эту единственную функцию. Если вы этого не сделали, вам нужно разделить функцию с возможностью внесения ошибок.
Параметры ввода действия
В идеале входные параметры должны быть меньше трех. Это просто упрощает тестирование функций. Я ожидаю, что это будет происходить чаще всего в CRUD-оболочке, которую вы напишете, так зачем останавливаться на достигнутом?
Это аргумент, который трудно защитить в OutSystems, потому что в OutSystems нам не хватает концепции классов и, следовательно, прекрасного способа иметь классную область видимости.
Тем не менее старайтесь минимизировать количество параметров, потому что чем больше параметров, тем выше вероятность того, что вы используете функцию более чем для одной цели.
Параметры флага
Это ужасная практика. Передача логического значения в действие почти означает, что действие выполняет одно действие, когда оно истинно, а другое - когда ложно. Это также означает, что у вас будет общее имя действия вместо двух понятных имен действий.
Возвращаясь к моему первому примеру, на основе логического значения я бы выбрал приложения, которые нужно игнорировать или нет. Но зачем мне передавать это логическое значение, было бы разумнее НЕ передавать его, а делать if для вызывающего действия. Возможно, это вызовет еще больший рефакторинг, но это будет означать, что у меня будут простые действия, которые можно будет протестировать отдельно.
Не имеют побочных эффектов
На самом деле, я надеюсь, что мне не нужно это говорить, но действия должны делать что-то одно, а не делать что-то секретное где-то еще, например, где-то изменять состояние записи.
Предпочитайте исключения, а не возвращаемые коды ошибок
Если вы используете коды ошибок, вам придется написать множество if-операторов, чтобы проверить, все ли пошло так, как ожидалось, или нет. Это создаст дополнительный код, фактически не имеющий никакой ценности для самого кода. С другой стороны, OutSystems не предоставляет отличного способа более детального перехвата исключений. Здесь нам нужно подумать о влиянии, которого мы хотим добиться. Обычно мы даже не хотим продолжать поток и все равно хотим откатить транзакцию, поэтому используйте исключение!
Не повторяйся
Еще одна очевидная задача в OutSystems. Если вы повторяете код, вам придется поддерживать код дважды, когда нужно будет изменить этот конкретный код. Опять же, внутри OutSystems не всегда легко, потому что это философия создания кода. Тем не менее, попробуйте распознать повторяющийся код и подумать, как его можно объединить в один, не нарушая других правил.
Заключение
Никогда не переставайте думать, делает ли действие то, что должно, и что оно подразумевает.
8. Что дальше?
Эти мысли должны вывести вас на новый уровень, когда вы будете классным разработчиком, весело проводящим время и создающим отличный код. Это первый шаг, и я надеюсь, что вы внесете часть этого в свой собственный код, чтобы иметь возможность иметь чистый код.