Aturan kode: kekuwatan menehi jeneng sing tepat, komentar apik lan ala

Sepira kerepe sampeyan kudu ngerti kode wong liya? Nalika, tinimbang sawetara jam, sampeyan nglampahi dina mung kanggo ngerti logika apa sing kedadeyan. Sing lucu yaiku kanggo wong sing nulis kode iki, kabeh jelas lan transparan. Lan iki ora nggumunake: sawise kabeh, kode sing sampurna utawa becik minangka konsep sing ora jelas, amarga saben pangembang duwe visi dhewe babagan jagad lan kode kasebut. Luwih saka sepisan aku nemoni kahanan nalika aku lan kanca-kancaku ndeleng kode sing padha lan beda-beda panemu babagan kabeneran lan kebersihan. Iku koyo sing akrab, ta? Nanging, ana sawetara titik sing diuji wektu sing kudu ditindakake, sing pungkasane bakal dimainake ing tangan kita, amarga yen sampeyan ninggalake kode ing negara sing sampeyan pengin nampa, jagad iki bakal dadi sethithik. luwih seneng lan resik. Ing artikel pungkasan kita bab aturan nulis kode (utawa rodo, guide cilik), kita ndemek sethitik ing Rekomendasi kanggo nulis sistem minangka kabèh lan unsur kayata obyek, antarmuka sing, kelas, cara lan variabel. Ing kana aku kanthi ringkes nyebutake jeneng unsur tartamtu sing bener. Dina iki aku pengin ngomong babagan iki, amarga jeneng sing bener nggawe maca kode luwih gampang. Kita bakal nutup topik kode sing bener kanthi bantuan refleksi lan conto cilik komentar ing kode - iki apik utawa ora apik. Dadi ayo miwiti.

Jeneng sing bener

Jeneng sing bener nambah keterbacaan kode kasebut, mula ngirit wektu kanggo familiarization, amarga luwih gampang nggunakake metode nalika jeneng kasebut nggambarake fungsine. Wiwit kabeh ing kode kasusun saka jeneng (variabel, cara, kelas, obyek file, etc.), titik iki dadi penting banget nalika nggawe bener, kode resik. Adhedhasar kasebut ing ndhuwur, jeneng kasebut kudu menehi makna kenapa, contone, variabel ana, apa sing ditindakake lan kepiye digunakake. Aku bakal nyathet maneh lan maneh yen komentar sing paling apik kanggo njlentrehake variabel yaiku jeneng sing bener.

Jeneng Antarmuka

Antarmuka biasane nggunakake jeneng sing diwiwiti kanthi huruf kapital lan ditulis ing kasus unta (CamelCase). Iki minangka praktik sing apik nalika nulis antarmuka kanggo prefix karo I kanggo nemtokake minangka antarmuka (contone IUserService), nanging iki cukup ala lan ngganggu. Ing kasus kaya mengkono, iku luwih apik kanggo nulis tanpa iku (UserService), lan nambah -Impl (UserServiceImpl) kanggo implementasine. Ya, utawa minangka pilihan pungkasan, tambahake awalan C (CUserService) kanggo implementasine.

Jeneng kelas

Kaya antarmuka, jeneng nganggo huruf kapital lan nggunakake gaya unta (CamelCase). Ora preduli apa jenis kiamat sing kedadeyan, ora preduli sepira cepet tenggat wektu, nanging aja, elinga, jeneng kelas ora kudu dadi kriya! Jeneng kelas lan obyek kudu dadi tembung lan kombinasi (UserController, UserDetails, UserAccount, lan liya-liyane). Sampeyan ora kudu menehi jeneng saben kelas kanthi singkatan saka aplikasi iki, amarga iki mung bakal nambah kerumitan sing ora perlu (contone, kita duwe aplikasi Migrasi Data Pengguna, lan kita bakal nambah UDM kanggo saben kelas - UDMUserDeatils, UDMUserAccount, UDMUserController ).

Jeneng metode

Biasane jeneng metode diwiwiti kanthi huruf cilik, nanging uga nggunakake gaya unta (CamelCase). Ndhuwur kita ngomong babagan kasunyatan manawa jeneng kelas ora kudu dadi kriya. Ing kene kahanane diametrically ngelawan: jeneng metode kudu kriya utawa kombinasi karo kriya: findUserById, findAllUsers, createUser, lan liya-liyane. Nalika nggawe metode (uga variabel lan kelas), supaya ora kebingungan, gunakake siji pendekatan jeneng. Contone, kanggo nemokake pangguna, cara kasebut bisa ditulis minangka getUserById utawa findUserById. Lan siji liyane: aja nggunakake humor ing jeneng metode, amarga padha ora ngerti guyonan, uga apa cara iki.

Jeneng variabel

Umume kasus, jeneng variabel diwiwiti kanthi huruf cilik lan uga nggunakake Camelcase, kajaba ing kasus sing variabel kasebut minangka konstanta global. Ing kasus kaya mengkono, kabeh aksara saka jeneng ditulis ing huruf gedhe lan tembung dipisahake dening underscore - "_". Nalika menehi jeneng variabel, sampeyan bisa nggunakake konteks sing migunani kanggo kepenak. Ing tembung liyane, nalika ana variabel minangka bagéan saka soko luwih gedhe - contone, firstName, lastName, status - ing kasus kaya mengkono sampeyan bisa nambah ater-ater sing nuduhake obyek kang variabel iki bagéan. Contone: userFirstName, userLastName, userStatus. Sampeyan uga kudu ngindhari jeneng sing padha kanggo variabel nalika duwe makna sing beda. Antonim umum kanggo variabel:

• wiwitan / pungkasan
• pisanan / pungkasan
• dikunci / dikunci
• min / maks
• sabanjure / sadurunge
• lawas / anyar
• dibukak / ditutup
• katon / ora katon
• sumber / target
• sumber/tujuan
• munggah mudhun

Jeneng variabel singkat

Nalika kita duwe variabel kaya x utawa n utawa kaya ngono, kita ora langsung weruh tujuane wong sing nulis kode kasebut. Iku ora ketok apa cara n nindakake: mbutuhake pikiran luwih wicaksana (lan iku wektu, wektu, wektu). Contone, kita duwe lapangan - id saka pangguna tanggung jawab, lan tinimbang sawetara jeneng kaya x utawa mung id, kita bakal nelpon variabel iki responsibleUserId, kang langsung nambah readability lan meaningfulness. Nanging, jeneng singkat kaya n panggonan minangka owah-owahan lokal kanggo cara cilik, ngendi pemblokiran kode karo owah-owahan sing mung sawetara baris kode, lan jeneng cara sampurna njlèntrèhaké apa mengkono ana. Pangembang, ndeleng variabel kasebut, ngerti pentinge sekunder lan ruang lingkup sing winates. Akibaté, ana sawetara katergantungan ing dawa jeneng variabel: luwih suwe, variabel global luwih akeh lan kosok balene. Contone, cara kanggo nemokake pangguna pungkasan sing disimpen miturut tanggal:

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

Ing kene kita nggunakake jeneng singkat x lan y kanggo nyetel urutan stream, lan lali babagan.

Dawane optimal

Ayo nerusake topik dawa jeneng. Dawane jeneng optimal ana ing antarane dawa jeneng maximumNumberOfUsersInTheCurrentGroup lan n. Yaiku, sing cendhak banget nandhang kekurangan makna, lan sing dawa banget babagan program kasebut tanpa nambah keterbacaan, lan mung kesed nulis saben-saben. Ora njupuk menyang akun cilik ndhuwur, kanggo variabel karo jeneng cendhak kaya n, sampeyan kudu tetep dawa kanggo kira-kira 8-16 karakter. Iki dudu aturan sing ketat: luwih minangka pedoman.

Bedane cilik

Aku ora bisa nglirwakake beda subtle ing jeneng, amarga iki uga laku ala, amarga sampeyan mung bisa bingung utawa nglampahi akèh wektu ekstra ngeweruhi beda cilik ing jeneng. Contone, prabédan antarane InvalidDataAccessApiUsageException lan InvalidDataAccessResourceUsageException angel ditemokake kanthi cepet. Uga, misinformation bisa asring muncul nalika nggunakake L lan O cilik, amarga padha bisa gampang bingung karo 1 lan 0: ing sawetara fonts prabédan luwih ketok, ing liyane kurang.

Bagian semantik

Kita kudu nglebokake bagean semantik menyang jeneng, nanging ora overplay karo sinonim, amarga, contone, UserData lan UserInfo bener duwe makna sing padha, lan kita kudu digali sethitik luwih jero menyang kode kanggo ngerti apa obyek tartamtu kita kudu. . Ngindhari tembung sing ora informatif, contone, firstNameString: kenapa kita butuh tembung string? Apa jeneng bisa dadi obyek jinis tanggal? Mesthi ora: mulane, mung - firstName. Minangka conto, aku pengin sebutno variabel boolean, contone, flagDelete. Tembung gendera ora nduweni teges semantik. Iku bakal wis luwih cukup kanggo nelpon - isDelete.

Disinformasi

Aku uga pengin ngomong sawetara tembung babagan jeneng sing salah. Ayo kita duwe jeneng userActivityList, lan obyek sing dijenengi ora saka jinis List, nanging sawetara wadhah liyane utawa obyek khusus kanggo panyimpenan. Iki bisa mbingungake programmer rata-rata: luwih becik diarani kaya userActivityGroup utawa userActivities.

Nggoleki

Salah sijine kekurangan jeneng sing cendhak lan prasaja yaiku angel ditemokake ing kode sing akeh, amarga apa sing bakal luwih gampang ditemokake: variabel sing diarani jeneng utawa NAME_FOR_DEFAULT_USER? Mesthi, pilihan kapindho. Sampeyan perlu kanggo ngindhari tembung (huruf) sing kerep ana ing jeneng, amarga iki mung bakal nambah jumlah file sing ditemokake sajrone panelusuran, sing ora apik. Kita pengin ngelingake sampeyan manawa programer luwih akeh wektu maca kode tinimbang nulis, mula elinga jeneng unsur aplikasi sampeyan. Nanging kepiye yen sampeyan ora bisa menehi jeneng kanthi sukses? Kepiye yen jeneng metode ora nggambarake fungsine kanthi apik? Iki minangka dolanan, item sabanjure yaiku komentar.

Komentar

Ora ana komentar sing cocog, nanging ora ana sing ngganggu modul kaya komentar sing ora ana guna, ketinggalan jaman, utawa mblusukake. Iku pedhang loro mata, ta? Nanging, sampeyan ora kudu nganggep komentar minangka kabecikan sing ora jelas: tinimbang, minangka ala sing luwih cilik. Sawise kabeh, komentar, ing intine, minangka ganti rugi kanggo pamikiran sing ora kasil ing kode kasebut. Contone, kita digunakake kanggo piye wae ngirim inti saka cara yen ternyata dadi banget bingung. Ing kahanan kaya mengkono, luwih becik refactor kode kasebut kanthi bener tinimbang nulis cathetan deskriptif. Sing luwih tuwa komentar, sing luwih elek, amarga kode kasebut cenderung tuwuh lan berkembang, nanging komentar kasebut bisa uga tetep padha, lan luwih akeh, cathetan kasebut dadi ragu-ragu. Komentar sing ora akurat luwih elek tinimbang ora komentar, amarga padha bingung lan ngapusi, menehi pangarepan palsu. Lan sanajan kita duwe kode banget angel, iku isih worth ora komentar ing, nanging nulis maneh.

Jinis komentar

• komentar legal minangka komentar sing ditinggalake ing wiwitan saben file kode sumber amarga alasan legal, kayata:

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

• komentar informatif - komentar sing menehi katrangan babagan kode (nyedhiyakake informasi tambahan utawa maksud saka bagean kode sing diwenehake.

  Minangka conto:

  /*
  * Объединяет пользователя из бд и пришедшего для обновления
  * Когда в 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()
         );
         }

  Ing kasus iki, sampeyan bisa nindakake tanpa komentar, amarga jeneng metode lan bantahane, ditambah karo fungsi sing transparan, cukup nggambarake awake dhewe.

• komentar peringatan - komentar sing tujuane kanggo ngelingake pangembang liyane babagan akibat sing ora dikarepake saka sawetara tumindak (contone, kenapa tes kasebut ditandhani minangka @Ignore):

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

• TODO - komentar sing cathetan kanggo mangsa sing kudu rampung, nanging sakperangan alesan ora bisa rampung saiki. Iki minangka praktik sing apik, nanging isih kudu ditinjau kanthi rutin kanggo mbusak sing ora relevan supaya ora keruwetan.

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

  //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, и подобный подход излишен.

• kode komentar iku kode sing wis komentar metu kanggo siji alesan utawa liyane. Salah sawijining kabiasaan sing paling awon, amarga sampeyan wis menehi komentar lan lali, lan pangembang liyane mung ora duwe keberanian kanggo mbusak (apa yen ana sing larang regane).

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

  Akibaté, akumulasi kaya sampah. Ing kahanan apa wae, kode kasebut ora kudu ditinggalake. Yen sampeyan pancene mbutuhake, aja lali babagan sistem kontrol versi.

• komentar sing ora jelas yaiku komentar sing njlèntrèhaké bab kanthi cara sing ora perlu.

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

  A komentar kudu nerangake kode, ora perlu panjelasan dhewe. Apa sing kedadeyan ing kene? Apa "saringan byte"? Apa hubungane +1 karo iki? Kenapa persis 300?

Yen sampeyan mutusake kanggo nulis komentar, ana sawetara tips kanggo nggunakake:

1. Gunakake gaya sing gampang dijaga: njaga gaya sing apik banget lan eksotis bisa ngganggu lan butuh wektu.
2. Aja nggunakake komentar ing mburi baris sing nuduhake siji baris: iki nggawe tumpukan gedhe saka komentar, lan iku angel teka munggah karo komentar ekspresif kanggo saben baris.
3. Nalika nggawe komentar, coba wangsulan pitakon "kenapa" tinimbang "kepriye".
4. Nyingkiri trabasan. Kaya sing dakkandhakake ing ndhuwur, kita ora butuh panjelasan kanggo komentar: komentar minangka panjelasan.
5. Sampeyan bisa nggunakake komentar kanggo menehi tandha unit pangukuran lan sawetara nilai sing bisa ditampa.
6. Selehake komentar sing cedhak karo kode sing digambarake.

Akibaté, aku isih pengin ngelingake sampeyan: komentar sing paling apik yaiku ora ana komentar, lan tinimbang, jeneng sing tepat ing aplikasi kasebut. Minangka aturan, umume kita bakal nggarap kode sing wis siap, njaga lan ngembangake. Iku luwih trep nalika kode iki gampang diwaca lan ngerti, amarga kode ala nemu ing dalan, sijine ngandika ing gembong, lan cepet-cepet kanca setya sawijining. Lan kode liyane ala sing kita duwe, kinerja liyane irungnya, supaya kita kudu refactor saka wektu kanggo wektu. Nanging yen wiwit wiwitan sampeyan nyoba nulis kode sing pangembang sabanjure ora pengin nemokake sampeyan lan mateni sampeyan, mula sampeyan kudu refactor kurang asring. Nanging isih perlu, amarga kahanan lan syarat kanggo produk saya ganti, ditambah karo sambungan tambahan, lan ora ana uwal saka iki. Pungkasan, aku bakal ninggalake sawetara tautan sing menarik kanggo sampeyan kenal karo topik iki ing kene , ing kene lan ing kene aku ngira kabeh iki kanggo aku dina iki, matur nuwun kanggo kabeh sing maca))