Haruskah orang berkomentar berbeda dalam bahasa fungsional? [Tutup]

25

Saya baru memulai dengan pemrograman fungsional dan saya bertanya-tanya tentang cara yang benar untuk mengomentari kode saya.

Tampaknya sedikit berlebihan untuk mengomentari fungsi pendek karena nama dan tanda tangan sudah seharusnya memberi tahu Anda semua yang perlu Anda ketahui. Mengomentari fungsi yang lebih besar juga tampaknya sedikit berlebihan karena mereka umumnya terdiri dari fungsi deskriptif diri yang lebih kecil.

Apa cara yang benar untuk mengomentari program fungsional? Haruskah saya menggunakan pendekatan yang sama seperti dalam pemrograman berulang?

functional-programming comments Tom Squires
sumber
7
"Karena mereka umumnya terdiri dari fungsi deskriptif diri yang lebih kecil." - itu, pada prinsipnya, tidak berbeda dalam bahasa imperatif. Masih sering tidak segera jelas apa fungsi besar akan dilakukan pada akhirnya: kita selalu dapat menyimpulkannya dari kode itu sendiri, tetapi jika itu membutuhkan waktu yang jauh lebih banyak daripada membaca komentar Anda harus memberikannya.
leftaroundabout
2
Saya tidak setuju. Karena bahasa Fungsional tidak memiliki efek samping Anda tahu persis apa yang akan dilakukan pada akhirnya, kembalikan nilai dengan tanda tangan yang diberikan
Tom Squires
8
tidak semua bahasa fungsional murni, beberapa memang memiliki efek samping.
Thanos Papathanasiou
1
Tetapi komentar apa yang Anda rasakan untuk berkomentar ... Ini overthink
gd1
1
Apakah proyek Anda berisiko memiliki anggota lain yang tidak terbiasa dengan bahasa fungsional? Mereka mungkin membutuhkan bantuan tambahan.
JeffO

Jawaban:

84

Nama fungsi harus mengatakan apa yang Anda lakukan.

Implementasinya akan memberi tahu Anda bagaimana melakukannya.

Gunakan komentar untuk menjelaskan mengapa Anda melakukannya.

Sean McMillan
sumber
1
Jawaban yang bagus, itu membunuh saya untuk melihat kode yang dikotori dengan komentar yang menjelaskan apa dan bagaimana (yang terbukti dari kode itu sendiri) tetapi membuat saya menebak mengapa.
Eric Wilson
32
dan ini benar terlepas dari paradigma
jk.
2
Ini mungkin tidak perlu dikatakan, tetapi Anda juga harus menambahkan komentar tentang apa dan bagaimana dalam kasus ini kode ini rumit atau berbelit-belit dan memerlukan penjelasan seperti itu. Tentu saja, kode seperti ini juga mungkin harus dihindari, tetapi itu tidak selalu mungkin.
user606723
3
Meskipun jawaban ini sangat sederhana dan kesederhanaan memang memiliki banyak nilai, itu tidak sepenuhnya benar. Nama fungsi seringkali tidak dan tidak bisa menggambarkan "apa" dengan cukup detail, sehingga dokumentasi sering diperlukan (misalnya untuk menggambarkan kasus tepi). Dokumentasi sering dimasukkan dalam komentar.
Luiscubal
2
Dapat diperdebatkan, nama fungsi juga harus menjelaskan mengapa ia melakukannya - bila memungkinkan.
Yam Marcovic
14

Jelas ada poin dalam pertanyaan ini, karena program fungsional biasanya berada pada tingkat abstraksi yang berbeda dari yang penting.

Karena itu, gaya dokumentasi lain diperlukan. Dalam program berulang komentar dapat membantu seperti dalam kode berikut, karena esensi kode tersembunyi di balik boilerplate:

// map 'toUpperCase' over 'container' yielding 'result'
Container result = new Container();
for (int i=0; i < container.size(); i++) { 
             result.addToTail(container.atElement(i).toUpperCase());
}

Tapi ini jelas omong kosong dalam bahasa fungsional:

-- map 'toUpperCase' over 'list'
let result = map toUpperCase list

Lebih baik:

-- we need the FooBars in all uppercase for the Frobnitz-Interface
let result = map toUpperCase list
Ingo
sumber
8
Kakek selalu menyuruh saya untuk mendokumentasikan mengapa bukan apa. Jadi saya akan menggunakan versi terakhir untuk kode imperatif juga.
Simon Bergot
3
Kakekmu benar. Saya hanya ingin menunjukkan bahwa komentar tertentu yang masuk akal namun di ranah imperatif sama sekali tidak berguna dalam funtional.
Ingo
11

Alasan kami mendokumentasikan suatu fungsi adalah karena pembaca tidak ingin atau tidak dapat membaca isi dari fungsi tersebut. Untuk alasan ini, seseorang harus mendokumentasikan fungsi besar, bahkan dalam bahasa fungsional. Tidak masalah jika mudah untuk memahami apa fungsinya dengan melihat implementasinya.

Joh
sumber
Poin yang bagus. Terutama jika pembaca menggunakan beberapa perpustakaan yang dikompilasi dan hanya dapat melihat tanda tangan fungsi yang terbuka dan komentar mereka. Mereka tidak akan pernah melihat nyali deskriptif diri dari kode Anda.
FrustratedWithFormsDesigner
3

Fungsi harus dikomentari, jika nama fungsi dan nama parameter saja tidak cukup untuk menentukan kontrak .

// returns a list of Employees    <-- not necessary
def GetEmployeeList: ...

// returns a list of Employees sorted by last name    <-- necessary
def GetEmployeeList: ...

Singkatnya, kontrak mendefinisikan apa yang diharapkan fungsi dan apa yang dijaminnya. Sebenarnya, jika GetEmployeeListmengembalikan daftar yang disortir tetapi tidak mengatakannya baik dalam nama fungsi atau komentar, konsumen fungsi ini tidak boleh mengandalkan perilaku ini. Ini adalah detail implementasi tanpa dokumen, dan penulis GetEmployeeListmemiliki kebebasan untuk mengubah perilaku ini kapan saja.

Heinzi
sumber
2

Komentar itu sendiri tidak boleh berisi deskripsi alternatif untuk apa kode itu (yang sebenarnya diungkapkan oleh kode itu sendiri), tetapi lebih merupakan penjelasan tentang alasan mengapa kode ditulis seperti itu.

Yang mengatakan, saya tidak melihat alasan mengapa komentar harus per se berbeda dalam bahasa fungsional.

perdian
sumber
1

Saya mengambil pendekatan yang sama untuk mendokumentasikan semua kode saya:

  • Gunakan nama deskriptif,
  • Tambahkan komentar sebelum logika yang cukup rumit jika logika rumit tidak dapat dihindari,
  • Tulis tinjauan umum dari seluruh sistem,

Jika nama dan jenis tanda tangan tidak memberi tahu Anda dengan tepat apa fungsi ini, Anda biasanya salah.

dan_waterworth
sumber
0

Pada usia 25 Anda cenderung mengingat hal-hal yang jauh lebih baik. Ketika Anda bertambah tua dan Anda terlibat dengan banyak sistem dengan kode legacy (ya, kode yang Anda tulis hari ini akan menjadi kode legacy dalam 10-15 tahun) akan sangat membantu jika ada komentar.

Michael Riley - AKA Gunny
sumber