Penamaan: Haruskah Anda mengorbankan kejelasan demi kejelasan?

11

Misalnya, fungsi berikut loop melalui array yang berisi nama dan kesalahan bidang input. Ini dilakukan dengan memeriksa nama bidang validasi dan kemudian mendorong info kesalahan ke array bidang yang tidak valid.

Apakah lebih baik untuk singkat dan menulis ini:

addInvalidField (field, message) {
  const foundField = this.invalidFields.find(value => {
    return value.name === field.name
  })
  const errors = foundField.errors
  if (!errors.some(error => error.name === message)) {
    errors.push({ name: message, message })
  }
},

Atau lebih spesifik seperti ini?

addInvalidField (validatingField, message) {
  const foundField = this.invalidFields.find(invalidField => {
    return validatingField.name === invalidField.name
  })
  if (!foundField.errors.some(foundFieldError => foundFieldError.name === message)) {
    fouldField.errors.push({ name: message, message })
  }
},
alex
sumber
1
related (mungkin duplikat): Apakah ada alasan untuk nama variabel pendek?
Agak
Jangan merasa ingin menulis jawaban, tetapi kami selalu berusaha menemukan kompromi yang baik antara panjang nama dan kejelasan. Nama pendek mungkin jelas bagi programmer asli tetapi tidak untuk orang lain. Nama panjang dapat membuat kode ini sulit dibaca. Ada kompromi di antaranya.
MetalMikester
1
perlu lebih banyak komentar
Ewan
Catatan samping, dan tidak yakin apakah itu mungkin dalam kode Anda, tetapi jika invalidFields dll disimpan dalam peta , bukan array , kode ini akan menjadi jauh lebih sederhana.
user949300
1
@alex Sebagai jawaban atas komentar Anda, Jika Anda bisa mendapatkan atau meminjam salinan Eloquent JavaScript oleh Marijn Haverbeke, (versi 2014) buka halaman 73-75 untuk melihat contoh hebat menggunakan peta alih-alih array. Semoga itu bisa membantu.
user949300

Jawaban:

23

Jika singkatnya dapat dikorbankan untuk kejelasan, itu harus. Tetapi jika verbositas dapat dikorbankan demi kejelasan, bahkan lebih baik.

addInvalidField (field, message) {
  const foundInvalidField = this.invalidFields.find(x => x.name === field.name)
  if (!foundInvalidField.errors.some(x => x.name === message)) {
    foundInvalidField.errors.push({ name: message, message })
  }
},

Ketika sebuah variabel hanya hidup selama satu baris, itu bisa sangat pendek. FoundInvalidFielddigunakan dalam tiga baris dan merupakan fokus dari pekerjaan ini. Itu layak nama yang jelas.

Seperti biasa, konteks adalah raja.

candied_orange
sumber
2
+1 untuk "Jika singkat dapat dikorbankan demi kejelasan, seharusnya. Tetapi jika verbositas dapat dikorbankan demi kejelasan, bahkan lebih baik." Bahkan ketika saya berusaha mencari kejelasan hampir di setiap keadaan. Tapi itu adalah kutipan yang pasti.
Tulains Córdova
12

Saya sebenarnya menyukai contoh kode pertama Anda.

Jelas terlihat apa yang dilakukan kode hanya dengan membacanya. Dengan menjaga nama variabel sekecil mungkin, Anda membuat kode lebih mudah dibaca. Nama variabel yang lebih deskriptif hanya akan diperlukan jika fungsi Anda lebih lama, variabel Anda lebih banyak dan / atau variabel digunakan pada cakupan kode yang lebih besar.

Itu karena Anda telah membuat fungsi Anda singkat sehingga Anda juga dapat membuat nama variabel Anda singkat. Semua hal lain dianggap sama, lebih sedikit kode selalu lebih baik.

Robert Harvey
sumber
2
Untuk mendukung ini, sebagai aturan umum, saya lebih suka nama variabel yang lebih kecil untuk metode / fungsi saya. Satu-satunya waktu saya akan menggunakan nama yang lebih verbose adalah jika ada konflik namespace. Jika ukuran fungsi Anda kecil, ini juga lebih mudah dilakukan.
unflores
4
Saya bekerja dengan seseorang yang sangat besar dalam nama verbal. variabel dan nama metode pada dasarnya adalah kalimat bahasa Inggris penuh misalnya theResultOfMethodDoFooWithBar. Idenya adalah bahwa ini seharusnya membuat semuanya menjadi jelas tetapi itu membuat saya sakit kepala mencoba mengurai (secara mental) semua bulu itu. Untuk contoh ini, kita sudah tahu metode ini tentang validasi bidang. Tidak ada parameter 'bidang' lainnya. Menggunakan nama seperti 'validatingField' tidak menambah kejelasan dan mengaburkan informasi penting saat membaca sekilas.
JimmyJames
@unflores Saya juga mencoba melakukan itu. validatingFieldsadalah bidang formulir dengan validasi. Nama aslinya adalah fieldWithValidation. Sangat sulit untuk menemukan nama pendek untuk yang satu ini. Saya bisa menyebutnya hanya fieldtapi kemudian akan ada konflik dengan yang lain fielddi dalam metode ini.
alex
4

Saya pikir saya setuju dengan Paman Bob untuk memilih kejelasan tanpa menimbulkan kata-kata yang berlebihan . Dalam contoh yang Anda tunjukkan, saya akan mengatakan bahwa niat orang kedua lebih jelas tanpa menimbulkan kata-kata yang berlebihan . Juga akan lebih mudah untuk menemukan potongan tertentu ketika mencari melalui basis kode invalidFielddaripada untuk value.


Yah saya mengutip Kode Bersih di sini (lewati saja jika Anda muak dengan khotbah Paman Bob (yang bukan aku):

Gunakan Nama yang Mengungkap Tujuan

Mudah untuk mengatakan bahwa nama harus mengungkapkan niat. Apa yang ingin kami berikan kepada Anda adalah bahwa kami serius tentang hal ini. Memilih nama baik membutuhkan waktu tetapi menghemat lebih banyak daripada yang dibutuhkan. Jadi berhati-hatilah dengan nama Anda dan ubahlah ketika Anda menemukan yang lebih baik. Setiap orang yang membaca kode Anda (termasuk Anda) akan lebih bahagia jika melakukannya.


Hindari Disinformasi

Pemrogram harus menghindari meninggalkan petunjuk palsu yang mengaburkan makna kode. Kita harus menghindari kata-kata yang maknanya yang berurat berakar berbeda dari kita


Buat Perbedaan yang Berarti

Pemrogram membuat masalah untuk diri mereka sendiri ketika mereka menulis kode semata-mata untuk memuaskan seorang kompiler atau juru bahasa.


Gunakan Nama yang Dapat Dicari

Gunakan nama yang akan membantu Anda melakukan grep -iIR whateveryouaresearching . (bukan Kode Bersih, di sini CC hanya berbicara tentang variabel huruf tunggal).


Hindari Pemetaan Mental

Pembaca tidak harus secara mental menerjemahkan nama Anda menjadi nama lain yang sudah mereka ketahui. Masalah ini umumnya muncul dari pilihan untuk tidak menggunakan istilah domain masalah atau istilah domain solusi.


Gunakan Masalah Nama Domain

Ketika tidak ada "programmer-eese" untuk apa yang Anda lakukan, gunakan nama dari domain masalah. Setidaknya programmer yang mengelola kode Anda dapat bertanya kepada pakar domain apa artinya.


Tulains Córdova
sumber
1

Saya selalu memilih untuk menjadi lebih deskriptif hari ini - Penyelesaian kode IDE berarti Anda tidak perlu menulis nama variabel deskriptif sehingga saya tidak dapat melihat sisi buruknya.

Kembali ke masa prasejarah, Anda memiliki batasan nama variabel dan menggunakan nama variabel yang berarti dapat benar-benar menimbulkan biaya yang terukur (misalnya di BBC BASIC menggunakan variabel statis bilangan bulat% D dll. Jauh lebih murah daripada menggunakan bilangan bulat bermakna - dan dalam sistem dengan 1MHz prosesor, menghemat beberapa siklus clock dalam satu loop sebenarnya penting)

mcottle
sumber
6
Kelemahannya adalah Anda tidak harus banyak mengetik. Pengetikan hanya terjadi satu kali. Kelemahan dari nama yang terlalu panjang adalah bahwa membaca menjadi lebih sulit. Dan itu berbahaya karena membaca terjadi berkali-kali selama umur basis kode, dan karena orang tidak secara sadar memperhatikan sumber masalahnya karena membaca sudah mendarah daging.
Kilian Foth
Dan jika Anda harus menghabiskan waktu dan perubahan konteks mencoba mengingat sesuatu tentang variabel karena tidak cukup deskriptif akan dikenakan biaya lebih banyak waktu :).
Mcottle
1

Varian kedua terlihat membuat saya bingung. Ketika saya hanya melihat tanda tangan, saya bertanya-tanya apakah bidang itu sudah dikenal sebagai beeing invalid? Atau akankah itu divalidasi terlebih dahulu (seperti namanya validatingField), untuk mengetahui apakah itu benar-benar tidak valid? Jadi ini bukan hanya informasi yang berlebihan di sini, informasi tambahan itu tampaknya agak menyesatkan. "Kejelasan" semacam ini tidak lebih jelas, justru sebaliknya.

Sebenarnya, ketika saya melihat fungsi pertama Anda, itu membuat saya bingung juga. Saya bertanya pada diri sendiri mengapa sih fungsi Anda hanya mengambil bidang, tetapi kemudian tidak menggunakannya dan mencari yang lain invalidFields? Mencari bidang tampaknya jauh lebih masuk akal ketika hanya ada nama bidang yang diberikan, seperti ini:

addInvalidField (fieldname, message) {
  const foundField = this.invalidFields.find(value => {
    return value.name === fieldname
  })
  const errors = foundField.errors
  if (!errors.some(error => error.name === message)) {
    errors.push({ name: message, message })
  }
}

Namun, saya kira Bob Martin mungkin akan melangkah lebih jauh dan membuat kode lebih bertele-tele - untuk lebih jelasnya - ke arah yang berbeda. Refactoring tipikal di sepanjang baris buku "Kode Bersih" mungkin akan terlihat seperti ini:

addInvalidField (fieldname, message) {
  const foundField = findInvalidField(fieldName)
  addMessageForInvalidField(foundField,message)
}

dengan tiga fungsi tambahan

  findInvalidField(fieldname){
    return this.invalidFields.find(value => { return value.name === fieldname })
  }

  addMessageForInvalidField(field,message){
    const errors = field.errors
    if (!doesErrorsContain(message)) {
      errors.push({ name: message, message })
    }
  }

  doesErrorsContain(message){
     return errors.some(error => error.name === message)
  }

Dapat diperdebatkan jika membayar sejauh itu dengan prinsip tanggung jawab tunggal. Sebenarnya ada beberapa pro dan kontra. Pandangan pribadi saya adalah bahwa kode asli "cukup bersih" untuk sebagian besar kode produksi, tetapi kode yang dire-refour lebih baik.

Ketika saya tahu saya harus menambahkan sesuatu ke varian pertama sehingga akan tumbuh lebih dan lebih, saya akan membaginya ke fungsi-fungsi yang lebih kecil sebelumnya, sehingga kode itu bahkan tidak akan mulai menjadi berantakan.

Doc Brown
sumber
validatingFieldsadalah bidang dalam formulir yang memiliki validasi. Awalnya, saya beri nama fieldsWithValidationtetapi agak panjang.
alex
0

Tidak ada jawaban yang benar secara umum dalam penamaan. Banyak orang ketika diberi set tugas yang sama persis akan menamai fungsi dan variabel yang dihasilkan sangat berbeda. Tentu saja Anda ingin orang lain yang membaca kode Anda mengerti, tetapi lebih lama tidak selalu berarti ada sesuatu yang lebih jelas. Jika kode Anda lebih padat maka perlu maka itu akan membutuhkan lebih banyak waktu untuk memahami bahkan setiap baris fungsi Anda sejelas dan deskriptif seperti itu.

Secara pribadi, saya lebih suka contoh pertama. Itu lurus dan to the point bahkan dengan variabel tidak memiliki nama deskriptif seperti pada contoh kedua. Sejujurnya, nama-nama variabel dalam contoh kedua tidak jauh lebih jelas daripada yang pertama menurut pendapat saya dan menjaga fungsi singkat membuatnya lebih mudah untuk memahami fungsi itu sendiri.

Pada akhirnya, mana yang lebih baik akan terserah Anda dan siapa pun yang bekerja dengan Anda. Bagaimanapun, itulah yang akan membacanya dan memeliharanya.

Dom
sumber