Код эрежелери: туура ат коюу күчү, жакшы жана жаман комментарийлер

Сиз канча жолу башка бирөөнүн codeун түшүнүүгө туура келди? Качан, бир-эки сааттын ордуна, сиз эмне болуп жатканын логикасын түшүнүү үчүн күндөрдү өткөрөсүз. Кызык жери, бул codeду жазган адам үчүн баары түшүнүктүү жана өтө тунук. Жана бул таң калыштуу эмес: баары бир кемчorксиз же идеалдуу code - бул өтө бүдөмүк түшүнүк, анткени ар бир иштеп чыгуучунун тиешелүүлүгүнө жараша дүйнө жана code жөнүндө өзүнүн көз карашы бар. Мен бир эмес, бир нече жолу кесиптешим экөөбүз бир codeду карап, анын тууралыгы жана тазалыгы боюнча ар кандай пикирде болгон жагдайга туш болдум. Бул тааныш сезим, туурабы? Бирок, сакталышы керек болгон кээ бир убакыт сыналган пункттар бар, алар акыры биздин пайдабызга иштейт, анткени эгер сиз codeуңузду өзүңүз каалаган абалда калтырсаңыз, дүйнө бир аз бактылуураак болмок жана тазалагыч. Кодду жазуу эрежелери жөнүндө акыркы макалабызда ( же тагыраак айтканда, кичинекей колдонмо) биз системаны бүтүндөй жазуу боюнча сунуштарга жана анын an objectилер, алардын интерфейстери, класстары, ыкмалары жана өзгөрмөлөрү сыяктуу элементтерине бир аз токтолдук. Ал жерде мен кээ бир элементтердин туура аталышын кыскача айтып өттүм. Бүгүн мен дал ушул жөнүндө айткым келет, анткени туура аталыштар codeду окууну бир топ жеңилдетет. Туура code темасын ой жүгүртүүнүн жана codeдогу комментарийлердин кичинекей мисалдарынын жардамы менен жабабыз - бул жакшыбы же анчалык жакшы эмеспи. Ошентип, баштайлы.

Туура ат коюу

Туура аталыштар codeдун окулушун жакшыртат, ошого жараша таанышууга убакытты үнөмдөйт, анткени аты болжолдуу түрдө анын функционалдуулугун сүрөттөп турганда ыкманы колдонуу бир топ жеңил болот. Коддогу бардык нерсе аталыштардан (өзгөрмөлөр, методдор, класстар, файл an objectилери ж.б.) тургандыктан, бул пункт туура, таза codeду түзүүдө абдан маанилүү болуп калат. Жогоруда айтылгандардын негизинде, ат, мисалы, өзгөрмө эмне үчүн бар экенин, ал эмне кылат жана кантип колдонулат деген маанини бериши керек. Мен кайра-кайра белгилей кетейин, өзгөрмөлөрдү сүрөттөө үчүн эң жакшы комментарий анын туура аталышы.

Интерфейстерди атоо

Интерфейстерде адатта баш тамга менен башталган жана төө тамгасы менен жазылган аталыштар колдонулат (CamelCase). Мурда интерфейсти жазууда аны интерфейс катары белгилөө үчүн аны I менен префикстөө жакшы практика болчу (мисалы, IUserService), бирок бул абдан жаман жана алаксытат. Мындай учурларда, ансыз жазуу жакшы (UserService), жана аны ишке ашыруу үчүн -Impl (UserServiceImpl) кошуу. Ооба, же акыркы чара катары, аны ишке ашырууга C (CUserService) префиксин кошуңуз.

Класс аттары

Интерфейстер сыяктуу эле, аттар баш тамга менен жазылат жана төө стorн (CamelCase) колдонушат. Кандай кыямат болбосун, мөөнөттөр канчалык тез болбосун, бирок эч качан, унутпаңыз, класстын аталышы эч качан этиш болбошу керек! Класс жана an object аттары зат атоочтор жана алардын айкалыштары болушу керек (UserController, UserDetails, UserAccount ж.б.). Ар бир класстын атын бул тиркеменин аббревиатурасы менен бербешиңиз керек, анткени бул керексиз татаалдыкты гана кошот (мисалы, бизде Колдонуучунун маалыматтарын көчүрүү тиркемеси бар жана биз ар бир класска UDM кошобуз - UDMUserDeatils, UDMUserAccount, UDMUserController ).

Метод аттары

Адатта ыкмалардын аталыштары кичине тамга менен башталат, бирок алар төө стorн да колдонушат (CamelCase). Жогоруда класс аттары эч качан этиш болбошу керектиги жөнүндө сөз кылдык. Бул жерде кырдаал таптакыр карама-каршы: методдордун аталыштары этиштер же алардын этиштер менен айкалышы болушу керек: findUserById, findAllUsers, createUser ж.б.у.с. Методду (ошондой эле өзгөрмөлөрдү жана класстарды) түзүүдө башаламандыкты болтурбоо үчүн, бир атоо ыкмасын колдонуңуз. Мисалы, колдонуучуну табуу үчүн, ыкманы getUserById же findUserById деп жазса болот. Жана дагы бир нерсе: методдордун атында юморду колдонбоңуз, анткени тамаша түшүнбөй калышы мүмкүн, ошондой эле бул ыкма эмне кылат.

Өзгөрмө аттары

Көпчүлүк учурларда, өзгөрмө аттары кичине тамга менен башталат жана ошондой эле өзгөрмө глобалдык константа болгон учурларды кошпогондо, Camelcase колдонушат. Мындай учурларда ысымдын бардык тамгалары баш тамга менен жазылат жана сөздөр астыңкы сызык менен бөлүнөт - “_”. Өзгөрмөлөрдү атоодо, сиз ыңгайлуулук үчүн маанилүү контекстти колдонсоңуз болот. Башкача айтканда, чоңураак нерсенин бир бөлүгү катары өзгөрмө болгондо - мисалы, ысым, фамorя, статус - мындай учурларда сиз бул өзгөрмө бөлүгү болгон an objectти көрсөтүүчү префиксти кошо аласыз. Мисалы: userFirstName, userLastName, userStatus. Ошондой эле өзгөрмөлөр такыр башка мааниге ээ болгондо окшош аттардан качышыңыз керек. Өзгөрмөлөрдүн жалпы антонимдери:

• баштоо/аяктоо
• биринчи акыркы
• кулпуланган/кулпусу ачылган
• мин/макс
• кийинки/мурунку
• Эски Жаңы
• ачылган/жабылган
• көрүнүүчү/көрүнбөгөн
• булак/максат
• булак/баруучу жер
• өйдө/төмөн

Кыска өзгөрмө аттары

Бизде x же n же ушул сыяктуу өзгөрмөлөр болгондо, биз codeду жазган адамдын ниетин дароо байкабайбыз. Бул ыкма n эмне кылганы түшүнүксүз: ал көбүрөөк ойлонууну талап кылат (жана бул убакыт, убакыт, убакыт). Мисалы, бизде талаа бар - жооптуу колдонуучунун идентификатору, жана x же жөн эле id сыяктуу кандайдыр бир аталыштын ордуна, биз бул өзгөрмөнү жооптууUserId деп атайбыз, бул дароо окулушун жана маанисин жогорулатат. Бирок, n сыяктуу кыска аталыштар чакан методдорго локалдык өзгөртүүлөр катары өз ордун ээлейт, мында бул өзгөртүү менен code блогу codeдун бир-эки саптарынан турат жана методдун аталышы ал жерде эмне болуп жатканын эң сонун сүрөттөйт. Иштеп чыгуучу мындай өзгөрмөнү көрүп, анын экинчи даражадагы маанисин жана өтө чектелген чөйрөсүн түшүнөт. Натыйжада, өзгөрмө аталышынын узундугуна кандайдыр бир көз карандылык бар: ал канчалык узун болсо, өзгөрмө ошончолук глобалдуу болот жана тескерисинче. Мисал катары, акыркы сакталган колдонуучуну датасы боюнча табуу ыкмасы:

public User findLastUser() {
   return findAllUsers().stream()
           .sorted((x, y) -> -x.getCreatedDate().compareTo(y.getCreatedDate()))
           .findFirst()
           .orElseThrow(() -> new ResourceNotFoundException("Any user doesn't exist "));
}

Бул жерде биз агымдын сортторун коюу үчүн x жана y кыска аталыштарын колдонобуз жана алар жөнүндө унутабыз.

Оптималдуу узундук

Ат узундугу темасын уланталы. Оптималдуу аталыш узундугу maksimumNumberOfUsersInTheCurrentGroup аталышынын узундугу менен n ортосунда болот. Башкача айтканда, өтө кыскалары маанисинин жетишсиздигинен жапа чегет, ал эми өтө узундары окумдуулукту кошпостон программаны созушат жана аларды ар дайым жазуудан жалкоо болушат. Жогорудагы жагдайды эске албаганда, n сыяктуу кыска аталыштагы өзгөрмөлөр үчүн узундукту болжол менен 8 -16 белгиге чейин сактоо керек. Бул катуу эреже эмес: көбүрөөк көрсөтмө.

Кичинекей айырмачылыктар

Мен ысымдардагы тымызын айырмачылыктарды этибарга албай коё албайм, анткени бул да жаман практика, анткени сиз жөн эле баш аламандыкка учурап же ысымдардагы анча-мынча айырмачылыктарды байкап калуу үчүн көп убакыт коротсоңуз болот. Мисалы, InvalidDataAccessApiUsageException менен InvalidDataAccessResourceUsageException ортосундагы айырманы бир караганда байкаш кыйын. Ошондой эле, туура эмес маалымат көп учурда кичинекей L жана O тамгаларын колдонууда пайда болушу мүмкүн, анткени аларды 1 жана 0 менен чаташтырууга болот: айрым шрифттерде айырма айкыныраак, башкаларында азыраак.

Семантикалык бөлүгү

Биз аттарга семантикалык бөлүгүн киргизишибиз керек, бирок синонимдер менен ашыкча ойношубуз керек, анткени, мисалы, UserData жана UserInfo иш жүзүндө бирдей мааниге ээ жана бизге кайсы конкреттүү an object керек экенин түшүнүү үчүн codeду бир аз тереңирээк казып алышыбыз керек. . Маалыматсыз сөздөрдөн алыс болуңуз, мисалы, firstNameString: бизге сап деген сөз эмне үчүн керек? Аталышы дата түрүндөгү an object болушу мүмкүнбү? Албетте, жок: ошондуктан, жөн гана - FirstName. Мисал катары, мен логикалык өзгөрмөлөрдү айткым келет, мисалы, flagDelete. Желек деген сөз эч кандай семантикалык мааниге ээ эмес. Аны - isDelete деп атоо акылга сыярлык.

Дезинформация

Туура эмес ат коюу жөнүндө да бир нече сөз айткым келет. Келгиле, бизде userActivityList деген ат бар дейли, жана ошондой аталган an object Тизме тибиндеги эмес, башка контейнер же сактоо үчүн ыңгайлаштырылган an object. Бул орточо программистти чаташтырышы мүмкүн: аны userActivityGroup же userActivities деп атасаңыз жакшы болмок.

Издөө

Кыска жана жөнөкөй аттардын кемчorктеринин бири - аларды көп сандагы codeдон табуу кыйын, анткени эмнени табуу оңой болмок: name же NAME_FOR_DEFAULT_USER деп аталган өзгөрмө? Албетте, экинчи вариант. Аттарда көп кездешүүчү сөздөрдү (тамгаларды) болтурбоо зарыл, анткени бул издөө учурунда табылган файлдардын санын гана көбөйтөт, бул жакшы эмес. Программисттер аны жазууга караганда codeду окууга көбүрөөк убакыт короторун эскертебиз, андыктан колдонмоңуздун элементтеринин аталышын эске алыңыз. Бирок аны ийгorктүү атай албасаңызчы? Эгерде методдун аталышы анын функционалдуулугун жакшы сүрөттөбөсөчы? Бул жерде ал оюнга кирет, биздин кийинки нерсе - комментарийлер.

Комментарийлер

Тиешелүү комментарийге окшош эч нерсе жок, бирок маанисиз, эскирген же адаштыруучу комментарийлер сыяктуу модулду эч нерсе бузbyte. Бул эки миздүү кылыч, туурабы? Ошентсе да, сиз комментарийлерге бир түшүнүктүү жакшылык катары мамиле кылбашыңыз керек: тескерисинче, азыраак жамандык катары. Анткени, комментарий, анын маңызы боюнча, codeексте ийгorксиз айтылган ойдун ордун толтуруу болуп саналат. Мисалы, эгерде ал өтө чаташкан болуп чыкса, биз аларды кандайдыр бир жол менен ыкманын маңызын жеткирүү үчүн колдонобуз. Мындай кырдаалда сүрөттөмө жазууларды жазгандан көрө, codeду туура рефакциялоо жакшы. Комментарий канчалык эски болсо, ошончолук начар, анткени code өсүп-өнүгүүгө умтулат, бирок комментарий ошол эле бойдон калышы мүмкүн жана ал барган сайын бул белгилер ошончолук күмөндүү болуп калат. Так эмес комментарийлер эч кандай комментарийлерге караганда алда канча жаман, анткени алар чаташтырышат жана жалган күтүүлөрдү беришет. Бизде өтө татаал code болсо дагы, ага комментарий бербей, кайра жазуу керек.

Комментарийлердин түрлөрү

• юридикалык комментарийлер ар бир баштапкы code файлынын башында юридикалык себептерден улам калтырылган комментарийлер, мисалы:

  * Copyright (c) 2007, 2013, Oracle and/or its affiliates. All rights reserved.
  * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.

• маалыматтык комментарийлер - codeдун түшүндүрмөсүн камтыган комментарийлер (кошумча маалыматты же codeдун берилген бөлүгүнүн ниетин көрсөтүүчү).

  Мисал катары:

  /*
  * Объединяет пользователя из бд и пришедшего для обновления
  * Когда в requestUser поле пустое, оно заполняется старыми данными из foundUser
  */
  private User mergeUser(User requestUser, User foundUser) {
         return new User(
         foundUser.getId(),
         requestUser.getFirstName() == null ? requestUser.getFirstName() : foundUser.getFirstName(),
         requestUser.getMiddleName() == null ? requestUser.getMiddleName() : foundUser.getMiddleName(),
         requestUser.getLastName() == null ? requestUser.getLastName() : foundUser.getLastName(),
         requestUser.getAge() == null ? requestUser.getAge() : foundUser.getAge()
         );
         }

  Бул учурда, сиз комментарийсиз эле кыла аласыз, анткени методдун аталышы жана анын аргументтери өтө ачык-айкын функционалдуулук менен бирге өзүн абдан жакшы сүрөттөйт.

• эскертүү комментарийи - максаты башка иштеп чыгуучуларга кандайдыр бир аракеттин жагымсыз кесепеттери жөнүндө эскертүү болгон комментарий (мисалы, эмне үчүн тест @Ignore деп белгиленген):

  // Слишком долго отрабатывает
  // Не запускайте, если не располагаете избытком времени
  @Ignore
  @Test
  public void someIntegrationTest() {
         ……
         }

• TODO - жасалышы керек болгон, бирок кандайдыр бир себептерден улам азыр аткарылбай турган келечек үчүн эскертүүлөр. Бул жакшы практика, бирок алар дагы эле баш аламандыкка жол бербөө үчүн тиешеси жокторун алып салуу үчүн үзгүлтүксүз карап чыгуу керек.

  Примером послужит:

  //TODO: Add a check for the current user ID (when will be created security context)
  
  @Override
  public Resource downloadFile(File file) {
         return fileManager.download(file);
         }

  Тут мы помечаем, что нужно добавить проверку юзера, который скачивает (id которого мы вытащим из security контекста) с тем, кто сохранил.

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

  Как пример, кусочек метода, заполняющий тестовую БД, некими скриптами:

  Stream.of(IOUtils.resourceToString("/fill-scripts/" + x, StandardCharsets.UTF_8)
         .trim()
         .split(";"))
         .forEach(jdbcTemplate::update);
  // Вызов trim() очень важен, убирает возможные пробелы в конце скрипта
  // чтобы при считке и разбивке на отдельные requestы не было пустых

• javaDoc — комментарии, которые описывают API определенного функционала для общего пользования. Наверное, самые полезные комментарии, так How с documentированным API в разы легче работать, но они также могут устаревать, How и любые другие. Поэтому не забываем, что главный вклад в documentацию вносится не комментариями, а хорошим codeом.

  Пример вполне обычного метода обновления пользователя:

  /**
  * Обновляет передаваемые поля для пользователя по id.
  *
  * @param id  id обновляемого пользователя
  * @param user пользователь с заполненными полями для обновления
  * @return обновленный пользователь
  */
         User update(Long id, User user);

Плохие сценарии комментариев

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

  Рассмотрим данный пример:

  public void configureSomeSystem() {
         try{
         String configPath = filesLocation.concat("/").concat(CONFIGURATION_FILE);
         FileInputStream stream = new FileInputStream(configPath);
         }  catch (FileNotFoundException e) {
         //В случае отсутствия конфигурационного file, загружается конфигурация по умолчанию
        }
  }

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

• избыточный комментарий — комментарий, который не несёт смысловой нагрузки, так How и так понятно что происходит в заданном участке codeа (он читается не проще, чем code).

  Смотрим пример:

  public class JdbcConnection{
  public class JdbcConnection{
     /**
      * Журнальный компонент, связанный с текущим классом
      */
     private Logger log = Logger.getLogger(JdbcConnection.class.getName());
  
     /**
      * Создаёт и возвращает connection с помощью входящих параметров
      */
     public static Connection buildConnection(String url, String login, String password, String driver) throws Exception {
         Class.forName(driver);
         connection = DriverManager.getConnection(url, login, password);
         log.info("Created connection with db");
         return connection;
     }

  Какой смысл таких комментариев, если мы и так всё прекрасно видим

• недостоверные комментарии — комментарии, не соответствующие истине и лишь вгоняющие в заблуждение (дезинформирующие). Как например:

  /**
  * Вспомогательный метод, закрывает соединение со сканером, если isNotUsing истинно
  */
  private void scanClose(Scanner scan, boolean isNotUsing) throws Exception {
     if (!isNotUsing) {
         throw new Exception("The scanner is still in use");
     } scan.close();
  }

  What в этом комменте не так? А то, что он немножко врёт нам, ведь соединение закрывается, если isNotUsing = false, но ниHow не наоборот, How нам вещает пометка.

• обязательные комментарии — комментарии, которые считают обязательными (Javadoc), но кои по факту иногда бывают излишне нагромождающими, недостоверными и ненужными (нужно задуматься, а нужны ли здесь такие комментарии).

  Пример:

  /**
  *  Creation пользователя по переданным параметрам
  * @param firstName Name созданного пользователя
  * @param middleName среднее Name созданного пользователя
  * @param lastName фамorя созданного пользователя
  * @param age возраст созданного пользователя
  * @param address addressс созданного пользователя
  * @return пользователь который был создан
  */
  User createNewUser(String firstName, String middleName, String lastName, String age, String address);

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

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

  /**
  *  Записи ведутся с 09 января 2020;
  **********************************************************************
  *  09.01.2020  : Обеспечение соединения с БД с помощью Jdbc Connection;
  *  15.01.2020  : Добавление интерфейсов уровня дао для работы с БД;
  *  23.01.2020  : Добавление интеграционных тестов для БД;
  *  28.01.2020  : Имплементация интерфейсов уровня дао;
  *  01.02.2020  : Разработка интерфейсов для сервисов,
  *  согласно требованиям прописанным в user stories;
  *  16.02.2020  : Имплементация интерфейсов сервисов
  *  (реализация бизнес логики связанной с работой БД);
  *  25.02.2020  : Добавление тестов для сервисов;
  *  08.03.2020  : Празднование восьмого марта(Миша опять в хлам);
  *  21.03.2020  : Рефакторинг сервис слоя;
  */

  Когда-то этот проход был оправдан, но с появлением систем управления исходным codeом (например — Git), это стало лишним нагромождением и усложнением codeа.

• комментарии ссылки на авторов — комментарии, преднаmeaningм которых является, указание человека, писавшего code, чтобы можно было связаться и обсудить, How что и зачем:

  * @author  Bender Benderovich

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

• комментарий берилген code - тигил же бул себептерден улам комментарий берилген code. Эң жаман адаттардын бири, анткени сиз аны комментарийлеп, унутуп калгансыз, жана башка иштеп чыгуучулардын аны өчүрүүгө батына алbyte (эгер бул баалуу нерсе болсочу).

  //    public void someMethod(SomeObject obj) {
  //    .....
  //    }

  Натыйжада, ал таштанды сыяктуу чогулат. Эч кандай шартта мындай code калтырылбашы керек. Эгер сизге чындап эле керек болсо, versionны башкаруу системасы жөнүндө унутпаңыз.

• ачык эмес комментарийлер – бир нерсени керексиз татаал түрдө сүрөттөгөн комментарийлер.

  /*
      * Начать с массива, размер которого достаточен для хранения
      * всех byteов данных (плюс byteы фильтра) с запасом, плюс 300 byte
      * для данных заголовка
      */
  this.dataBytes = new byte[(this.size * (this.deep + 1) * 2)+300];

  Комментарий codeду түшүндүрүшү керек, түшүндүрүүнүн өзүнө кереги жок. Бул жерде эмне бар? "Фыпка byteтары" деген эмне? +1 мунун кандай тиешеси бар? Эмне үчүн так 300?

Эгерде сиз комментарий жазууну чечсеңиз, бул жерде аларды колдонуу боюнча бир нече кеңеш бар:

1. Колдонуу оңой болгон стилдерди колдонуңуз: өтө кооз жана экзотикалык стилдерди сактоо тажатма жана убакытты талап кылышы мүмкүн.
2. Жалгыз саптарга шилтеме берген саптардын аягындагы комментарийлерди колдонбоңуз: бул комментарийлердин чоң үймөгүн түзөт жана ар бир сапка экспрессивдүү комментарий берүү кыйын.
3. Комментарий жазууда "кантип" эмес, "эмне үчүн" деген суроого жооп бергенге аракет кылыңыз.
4. Кыскартуулардан алыс болуңуз. Мен жогоруда айткандай, комментарийге түшүндүрмөнүн кереги жок: комментарий – бул түшүндүрмө.
5. Өлчөө бирдиктерин жана алгылыктуу маанилердин диапазонун белгилөө үчүн комментарийлерди колдоно аласыз.
6. Комментарийлерди алар сүрөттөгөн codeго жакын жайгаштырыңыз.

Натыйжада, мен дагы эле эскертип кетким келет: эң жакшы комментарийлер - бул комментарийдин жоктугу, анын ордуна тиркемеде туура ат коюу. Эреже катары, биз көп учурда даяр code менен иштеп, аны сактап жана кеңейтебиз. Бул codeду окуу жана түшүнүү оңой болгондо алда канча ыңгайлуу, анткени жаман code жолго түшүп, дөңгөлөккө сүйлөм салып, шашылыш анын ишенимдүү шериги болот. Ал эми бизде канчалык начар code болсо, ошончолук өндүрүмдүүлүк төмөндөйт, андыктан биз мезгил-мезгor менен рефакторлорду жасап турушубуз керек. Бирок эгер сиз башынан эле code жазууга аракет кылсаңыз, ал үчүн кийинки иштеп чыгуучулар сизди таап, өлтүргүсү келбесе, анда сиз аны азыраак рефакторлооңуз керек болот. Бирок бул дагы эле зарыл болот, анткени буюмга карата шарттар жана талаптар тынымсыз өзгөрүп, кошумча байланыштарды кошуу менен толукталат жана мындан кутулуу мүмкүн эмес. Акыр-аягы, мен бул тема менен таанышуу үчүн бир нече кызыктуу шилтемелерди калтырам , бул жерде жана бул жерде мен бүгүн мен үчүн бардыгын ойлоп жатам, окугандардын баарына рахмат))