Aturan kode: kekuatan penamaan yang tepat, komentar baik dan buruk

Seberapa sering Anda harus memahami kode orang lain? Ketika, alih-alih beberapa jam, Anda menghabiskan waktu berhari-hari hanya untuk memahami logika dari apa yang terjadi. Lucunya bagi orang yang menulis kode ini, semuanya jelas dan sangat transparan. Dan ini tidak mengherankan: bagaimanapun juga, kode yang sempurna atau ideal adalah konsep yang sangat kabur, karena setiap pengembang memiliki visinya sendiri tentang dunia dan kodenya masing-masing. Lebih dari sekali saya menemukan situasi di mana saya dan kolega saya melihat kode yang sama dan memiliki pendapat berbeda tentang kebenaran dan kebersihannya. Perasaan yang familiar, bukan? Namun, ada beberapa poin yang telah teruji oleh waktu yang harus dipatuhi, yang pada akhirnya akan menguntungkan kita, karena jika Anda membiarkan kode Anda dalam keadaan yang Anda sendiri ingin menerimanya, dunia akan menjadi sedikit lebih bahagia dan pembersih. Dalam artikel terakhir kami tentang aturan penulisan kode (atau lebih tepatnya, panduan kecil), kami sedikit menyentuh rekomendasi untuk menulis sistem secara keseluruhan dan elemen-elemennya seperti objek, antarmuka, kelas, metode, dan variabel. Di sana saya secara singkat menyebutkan penamaan yang benar untuk unsur-unsur tertentu. Hari ini saya ingin membicarakan hal ini, karena nama yang benar membuat kode lebih mudah dibaca. Kami akan menutup topik kode yang benar dengan bantuan refleksi dan contoh kecil komentar dalam kode - apakah ini bagus atau tidak. Jadi mari kita mulai.

Penamaan yang benar

Nama yang benar meningkatkan keterbacaan kode, sehingga menghemat waktu dalam pengenalan, karena lebih mudah menggunakan metode ketika nama tersebut secara kasar menggambarkan fungsinya. Karena segala sesuatu dalam kode terdiri dari nama (variabel, metode, kelas, objek file, dll.), poin ini menjadi sangat penting saat membuat kode yang benar dan bersih. Berdasarkan penjelasan di atas, nama harus menyampaikan arti mengapa, misalnya, suatu variabel ada, apa fungsinya, dan bagaimana penggunaannya. Saya akan mencatat berulang kali bahwa komentar terbaik untuk mendeskripsikan suatu variabel adalah nama yang benar.

Antarmuka Penamaan

Antarmuka biasanya menggunakan nama yang dimulai dengan huruf kapital dan ditulis dalam huruf unta (CamelCase). Dulu merupakan praktik yang baik ketika menulis sebuah antarmuka untuk mengawalinya dengan I untuk menetapkannya sebagai antarmuka (misalnya IUserService), tetapi ini cukup jelek dan mengganggu. Dalam kasus seperti itu, lebih baik menulis tanpa itu (UserService), dan menambahkan -Impl (UserServiceImpl) ke implementasinya. Nah, atau sebagai upaya terakhir, tambahkan awalan C (CUserService) ke implementasinya.

Nama kelas

Sama seperti antarmuka, nama menggunakan huruf kapital dan menggunakan gaya unta (CamelCase). Tidak peduli kiamat macam apa yang terjadi, tidak peduli seberapa cepat tenggat waktu, tapi jangan pernah, ingat, nama kelas tidak boleh berupa kata kerja! Nama kelas dan objek harus berupa kata benda dan kombinasinya (UserController, UserDetails, UserAccount, dan sebagainya). Anda tidak boleh memberikan nama setiap kelas dengan singkatan aplikasi ini, karena ini hanya akan menambah kerumitan yang tidak perlu (misalnya, kami memiliki aplikasi Migrasi Data Pengguna, dan kami akan menambahkan UDM ke setiap kelas - UDMUserDeatils, UDMUserAccount, UDMUserController ).

Nama metode

Biasanya nama metode dimulai dengan huruf kecil, tetapi metode tersebut juga menggunakan gaya unta (CamelCase). Di atas kita berbicara tentang fakta bahwa nama kelas tidak boleh berupa kata kerja. Di sini situasinya sangat berlawanan: nama metode harus berupa kata kerja atau kombinasinya dengan kata kerja: findUserById, findAllUsers, createUser, dan seterusnya. Saat membuat metode (serta variabel dan kelas), untuk menghindari kebingungan, gunakan satu pendekatan penamaan. Misalnya, untuk mencari pengguna, metodenya dapat ditulis sebagai getUserById atau findUserById. Dan satu hal lagi: jangan menggunakan humor dalam mengatasnamakan metode, karena mereka mungkin tidak memahami leluconnya, serta apa fungsi metode ini.

Nama variabel

Dalam kebanyakan kasus, nama variabel dimulai dengan huruf kecil dan juga menggunakan huruf Camel, kecuali jika variabel tersebut adalah konstanta global. Dalam kasus seperti itu, semua huruf nama ditulis dalam huruf besar dan kata-katanya dipisahkan dengan garis bawah - “_”. Saat memberi nama variabel, Anda dapat menggunakan konteks yang bermakna demi kenyamanan. Dengan kata lain, ketika ada variabel sebagai bagian dari sesuatu yang lebih besar - misalnya, Nama Depan, Nama Belakang, status - dalam kasus seperti itu, Anda dapat menambahkan awalan yang menunjukkan objek di mana variabel tersebut menjadi bagiannya. Misalnya: namapenggunaNamaPertama,NamaPengguna,Statuspengguna. Anda juga perlu menghindari nama variabel yang mirip ketika variabel tersebut memiliki arti yang sangat berbeda. Antonim umum untuk variabel:

• mulai/akhir
• pertama/terakhir
• terkunci/tidak terkunci
• min/maks
• selanjutnya/sebelumnya
• lama/baru
• dibuka/ditutup
• terlihat/tidak terlihat
• sumber/sasaran
• sumber tujuan
• atas/bawah

Nama variabel pendek

Ketika kita memiliki variabel seperti x atau n atau semacamnya, kita tidak langsung melihat niat orang yang menulis kode tersebut. Tidak jelas apa yang dilakukan metode n: metode ini memerlukan pemikiran yang lebih bijaksana (dan itulah waktu, waktu, waktu). Misalnya, kita memiliki bidang - id pengguna yang bertanggung jawab, dan alih-alih nama seperti x atau hanya id, kita akan memanggil variabel ini bertanggung jawabUserId, yang segera meningkatkan keterbacaan dan kebermaknaan. Namun, nama pendek seperti n memiliki tempatnya sebagai perubahan lokal pada metode kecil, di mana blok kode dengan perubahan tersebut hanyalah beberapa baris kode, dan nama metode dengan sempurna menggambarkan apa yang terjadi di sana. Pengembang, melihat variabel seperti itu, memahami kepentingan sekundernya dan cakupannya yang sangat terbatas. Akibatnya, terdapat ketergantungan pada panjang nama variabel: semakin panjang, semakin global variabel tersebut dan sebaliknya. Sebagai contoh, metode untuk menemukan pengguna terakhir yang disimpan berdasarkan tanggal:

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

Di sini kita menggunakan nama pendek x dan y untuk mengatur pengurutan aliran, dan melupakannya.

Panjang optimal

Mari kita lanjutkan topik panjang nama. Panjang nama optimal berada di antara panjang nama maksimumNumberOfUsersInTheCurrentGroup dan n. Artinya, yang terlalu pendek akan kurang bermakna, dan yang terlalu panjang akan meregangkan program tanpa menambah keterbacaan, dan mereka terlalu malas untuk menulisnya setiap saat. Tanpa memperhitungkan kasus di atas, untuk variabel dengan nama pendek seperti n, Anda harus menjaga panjangnya kurang lebih 8 -16 karakter. Ini bukan aturan ketat: lebih merupakan pedoman.

Perbedaan kecil

Saya tidak dapat mengabaikan perbedaan halus dalam nama, karena ini juga merupakan praktik yang buruk, karena Anda bisa saja menjadi bingung atau menghabiskan banyak waktu ekstra untuk memperhatikan perbedaan kecil dalam nama. Misalnya, perbedaan antara InvalidDataAccessApiUsageException dan InvalidDataAccessResourceUsageException sulit dikenali secara sekilas. Selain itu, kesalahan informasi sering kali muncul saat menggunakan L dan O kecil, karena mudah tertukar dengan 1 dan 0: pada beberapa font perbedaannya lebih jelas, pada font lainnya kurang jelas.

Bagian semantik

Kita perlu memasukkan bagian semantik ke dalam nama, tetapi tidak berlebihan dengan sinonim, karena, misalnya, UserData dan UserInfo sebenarnya memiliki arti yang sama, dan kita harus menggali lebih dalam kode untuk memahami objek spesifik apa yang kita butuhkan. . Hindari kata-kata yang tidak informatif, misalnya firstNameString: mengapa kita memerlukan kata string? Bisakah sebuah nama menjadi objek tipe tanggal? Tentu saja tidak: oleh karena itu, cukup - Nama Depan. Sebagai contoh, saya ingin menyebutkan variabel boolean, misalnya flagDelete. Kata bendera tidak memiliki arti semantik apa pun. Akan lebih masuk akal untuk menyebutnya - isDelete.

Disinformasi

Saya juga ingin menyampaikan beberapa patah kata tentang penamaan yang salah. Katakanlah kita memiliki nama userActivityList, dan objek yang diberi nama tersebut bukan tipe Daftar, tetapi beberapa wadah atau objek khusus lain untuk penyimpanan. Hal ini dapat membingungkan programmer rata-rata: akan lebih baik untuk menyebutnya sesuatu seperti userActivityGroup atau userActivities.

Mencari

Salah satu kelemahan nama pendek dan sederhana adalah sulit ditemukan dalam kode yang banyak, karena mana yang lebih mudah ditemukan: variabel bernama nama atau NAME_FOR_DEFAULT_USER? Tentu saja pilihan kedua. Kata (huruf) yang sering muncul dalam nama harus dihindari, karena ini hanya akan menambah jumlah file yang ditemukan selama pencarian, dan ini tidak baik. Kami ingin mengingatkan Anda bahwa pemrogram menghabiskan lebih banyak waktu untuk membaca kode daripada menulisnya, jadi berhati-hatilah dalam memberi nama pada elemen aplikasi Anda. Tetapi bagaimana jika Anda tidak berhasil memberi nama? Bagaimana jika nama suatu metode tidak menggambarkan fungsinya dengan baik? Di sinilah peranannya, item kami berikutnya adalah komentar.

Komentar

Tidak ada komentar yang relevan, namun tidak ada yang mengacaukan modul seperti komentar yang tidak bermakna, ketinggalan jaman, atau menyesatkan. Itu adalah pedang bermata dua, bukan? Namun, Anda tidak boleh memperlakukan komentar sebagai suatu kebaikan yang jelas: sebaliknya, sebagai kejahatan yang lebih kecil. Bagaimanapun, sebuah komentar, pada intinya, adalah kompensasi atas pemikiran yang tidak berhasil diungkapkan dalam kode. Misalnya, kami menggunakannya untuk menyampaikan inti dari metode ini jika ternyata terlalu membingungkan. Dalam situasi seperti ini, lebih baik memfaktorkan ulang kode dengan benar daripada menulis catatan deskriptif. Semakin tua komentarnya, semakin buruk, karena kodenya cenderung tumbuh dan berkembang, namun komentarnya bisa tetap sama, dan semakin jauh, semakin meragukan catatan tersebut. Komentar yang tidak akurat jauh lebih buruk daripada tidak berkomentar, karena membingungkan dan menipu, memberikan ekspektasi yang salah. Dan meskipun kita memiliki kode yang sangat rumit, tetap ada baiknya untuk tidak mengomentarinya, tetapi menulis ulang.

Jenis komentar

• komentar hukum adalah komentar yang ditinggalkan di awal setiap file kode sumber karena alasan hukum, seperti:

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

• Komentar informatif adalah komentar yang memberikan penjelasan tentang kode (memberikan informasi tambahan atau maksud dari potongan kode tertentu.

  Sebagai contoh:

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

  Dalam hal ini, Anda dapat melakukannya tanpa komentar, karena nama metode dan argumennya, ditambah dengan fungsionalitas yang sangat transparan, menggambarkan dirinya dengan cukup baik.

• komentar peringatan - komentar yang tujuannya adalah untuk memperingatkan pengembang lain tentang konsekuensi yang tidak diinginkan dari beberapa tindakan (misalnya, mengapa pengujian ditandai sebagai @Ignore):

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

• TODO - komentar yang merupakan catatan untuk kedepannya yang perlu dilakukan, namun entah kenapa tidak bisa dilakukan saat ini. Ini adalah praktik yang baik, namun tetap perlu ditinjau secara berkala untuk menghapus yang tidak relevan guna menghindari kekacauan.

  Contohnya adalah:

  //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);
         }

  Di sini kita perhatikan bahwa kita perlu menambahkan tanda centang pada pengguna yang mengunduh (yang idnya akan kita keluarkan dari konteks keamanan) dengan orang yang menyimpan.

• komentar yang memperkuat - komentar yang menekankan pentingnya suatu keadaan, yang pada pandangan pertama mungkin tampak tidak penting.

  Sebagai contoh, bagian dari metode yang mengisi database pengujian dengan beberapa skrip:

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

• javaDoc - komentar yang menjelaskan API fungsionalitas tertentu untuk penggunaan umum. Mungkin komentar yang paling berguna, karena API yang terdokumentasi lebih mudah digunakan, tetapi bisa juga menjadi usang, seperti yang lainnya. Oleh karena itu, jangan lupa bahwa kontribusi utama dokumentasi bukanlah komentar, melainkan kode yang baik.

  Contoh metode pembaruan pengguna yang sepenuhnya normal:

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

Skrip komentar yang buruk

• komentar bergumam - komentar yang biasanya ditulis dengan tergesa-gesa, yang maknanya hanya jelas bagi pengembang yang menulisnya, karena hanya dia yang melihat situasi dengan nuansa yang dirujuknya.

  Perhatikan contoh ini:

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

  Siapa yang memuat pengaturan ini? Apakah sudah pernah diunduh sebelumnya? Apakah metode ini dimaksudkan untuk mencegat pengecualian dan memanggil pengaturan default? Terlalu banyak pertanyaan yang muncul, jawabannya hanya dapat diperoleh dengan mempelajari bagian lain dari sistem.

• komentar redundan adalah komentar yang tidak membawa muatan semantik apa pun, karena sudah jelas apa yang terjadi di bagian kode tertentu (tidak lebih mudah dibaca daripada kode).

  Mari kita lihat sebuah contoh:

  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;
     }

  Apa gunanya komentar seperti itu jika kita sudah melihat semuanya dengan sempurna

• komentar palsu – komentar yang tidak sesuai dengan kebenaran dan hanya menyesatkan (misinform). Seperti:

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

  Apa yang salah dengan komentar ini? Dan fakta bahwa dia sedikit berbohong kepada kita, karena koneksi ditutup jika isNotUsing = false, tetapi tidak sebaliknya, seperti yang ditunjukkan oleh tanda tersebut.

• komentar wajib - komentar yang dianggap wajib (Javadoc), tetapi sebenarnya terkadang terlalu berantakan, tidak dapat diandalkan, dan tidak perlu (Anda perlu memikirkan apakah komentar tersebut diperlukan di sini).

  Contoh:

  /**
  *  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);

  Apakah Anda dapat memahami apa yang dilakukan metode ini tanpa komentar-komentar ini? Kemungkinan besar ya, jadi komentar dalam hal ini menjadi tidak ada artinya.

• komentar jurnal adalah komentar yang terkadang ditambahkan ke awal modul setiap kali modul diedit (seperti log perubahan yang dibuat).

  /**
  *  Записи ведутся с 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  : Рефакторинг сервис слоя;
  */

  Pada suatu waktu, bagian ini dibenarkan, tetapi dengan munculnya sistem manajemen kode sumber (misalnya, Git), hal ini menjadi kekacauan dan kerumitan kode yang tidak perlu.

• komentar tautan ke penulis - komentar yang tujuannya untuk menunjukkan orang yang menulis kode, sehingga Anda dapat menghubungi dan mendiskusikan bagaimana, apa dan mengapa:

  * @author  Bender Benderovich

  Sekali lagi, sistem kontrol versi mengingat dengan sempurna siapa yang menambahkan kode ini dan kapan, dan pendekatan ini tidak diperlukan.

• Kode yang dikomentari adalah kode yang dikomentari karena satu dan lain hal. Salah satu kebiasaan terburuk, karena Anda berkomentar dan lupa, dan pengembang lain tidak berani menghapusnya (bagaimana jika itu adalah sesuatu yang berharga).

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

  Akibatnya menumpuk seperti sampah. Dalam situasi apa pun kode tersebut tidak boleh dibiarkan. Jika Anda benar-benar membutuhkannya, jangan lupakan sistem kontrol versinya.

• komentar yang tidak jelas adalah komentar yang menggambarkan sesuatu dengan cara yang rumit dan tidak perlu.

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

  Sebuah komentar harus menjelaskan kodenya, tidak memerlukan penjelasan itu sendiri. Apa disini? Apa itu "filter byte"? Apa hubungannya +1 dengan ini? Kenapa tepatnya 300?

Jika Anda memutuskan untuk menulis komentar, berikut beberapa tip untuk menggunakannya:

1. Gunakan gaya yang mudah dirawat: mempertahankan gaya yang terlalu mewah dan eksotis dapat mengganggu dan memakan waktu.
2. Jangan gunakan komentar di akhir baris yang mengacu pada satu baris: ini akan menimbulkan banyak komentar, dan sulit untuk memberikan komentar ekspresif untuk setiap baris.
3. Saat membuat komentar, cobalah menjawab pertanyaan “mengapa” daripada “bagaimana”.
4. Hindari jalan pintas. Seperti yang saya katakan di atas, kita tidak memerlukan penjelasan untuk sebuah komentar: komentar adalah penjelasannya.
5. Anda dapat menggunakan komentar untuk menandai satuan pengukuran dan rentang nilai yang dapat diterima.
6. Tempatkan komentar di dekat kode yang dijelaskannya.

Oleh karena itu, saya tetap ingin mengingatkan Anda: komentar terbaik adalah tidak adanya komentar, dan sebagai gantinya, penamaan yang tepat dalam aplikasi. Biasanya, sebagian besar waktu kita bekerja dengan kode yang sudah jadi, memelihara dan mengembangkannya. Jauh lebih nyaman bila kode ini mudah dibaca dan dipahami, karena kode yang buruk menghalangi, memberikan pengaruh, dan tergesa-gesa adalah teman setianya. Dan semakin banyak kode buruk yang kita miliki, semakin banyak penurunan kinerja, jadi kita perlu melakukan refaktorisasi dari waktu ke waktu. Tetapi jika sejak awal Anda mencoba menulis kode yang pengembang selanjutnya tidak ingin menemukan dan membunuh Anda, maka Anda perlu lebih jarang melakukan refaktorisasi. Namun hal itu tetap diperlukan, karena kondisi dan persyaratan produk terus berubah, ditambah dengan penambahan koneksi tambahan, dan tidak ada jalan keluar dari hal ini. Terakhir, saya akan meninggalkan beberapa tautan menarik agar Anda dapat mengenal topik ini di sini , di sini dan di sini . Saya rasa itu saja untuk saya hari ini, terima kasih kepada semua orang yang membaca))