platform apa yang terbaik untuk menjelaskan kode semu kepada pengembang yang tidak tahu apa-apa tentang itu? [Tutup]

8

Saya orang ilmiah yang perlu mendokumentasikan kode Matlab yang kompleks untuk diserahkan kepada pengembang agar dia mengerti dan memprogram dalam bahasa yang berbeda. Di masa lalu, saya telah menggunakan MS Word (menjelaskan setiap langkah program sebagai baris baru dalam sebuah tabel), dan kemudian Excel, tetapi tidak menemukan yang sangat cocok untuk menampilkan kode Matlab saya dan memasukkan komentar secara jelas dan ringkas. cara mendokumentasikannya.

Saya ingin tahu apakah ada teknik yang lebih baik untuk mengkomunikasikan kode semu kepada pengembang. Adakah perangkat lunak yang ada (gratis?) Atau platform lain (mis. TextWrangler) sangat cocok untuk menyediakan kode dan beberapa metode untuk menjelaskannya? Berharap untuk belajar dari pengalaman orang lain melakukan hal yang sama. Terima kasih sebelumnya.

Setelah membaca beberapa komentar, izinkan saya mencoba menjelaskan lebih lanjut ... Saya menganggap semua pengembang tahu pseudo-code, tapi saya tidak berasumsi banyak yang tahu kode Matlab. Jadi, jika saya menulis dalam pseudo-code, saya dapat mengabaikan kode Matlab (atau memberikannya untuk referensi, dll.). Tetapi pertanyaan saya sangat sederhana ... apakah ada perangkat lunak atau platform yang digunakan orang di masa lalu untuk mengkomunikasikan kode dengan jelas kepada pengembang? Sesuatu yang memungkinkan orang membuat dokumen dengan mudah menggambarkan kode? Misalnya, Anda dapat menanamkan kode warna kode perangkat lunak (satu warna untuk komentar, satu lagi untuk kata-kata yang dicadangkan (jika, kemudian, yang lain, untuk, dll.), Dll.), Dan di satu sisi ada ruang bagi saya untuk memasukkan penjelasan dan referensi, dll. Saya mencoba melakukan ini menggunakan produk MS, tetapi berpikir karena ada industri orang yang perlu melakukan hal yang sama,

pseudocode gkdsp
sumber
1
Saya ingin tahu apakah pertanyaan ini hanya kata-kata yang buruk atau saya salah paham. Bagaimana mungkin seorang pengembang tidak mengerti apa itu kodesemu? Apakah Anda berbicara tentang dokumen tingkat tinggi tentang cara kerja program?
Daenyth
4
Mengapa memberi pseudocode pengembang? Mengapa tidak memberi mereka kode Matlab itu dan membiarkan mereka mengonversinya sendiri? Pengembang yang layak harus dapat mempelajari Matlab dan mencari tahu cara kerja program.
FrustratedWithFormsDesigner
1
Saya pikir dia menggambarkan pengembang yang tidak tahu apa-apa tentang MatLAB, yang bahkan dapat dimengerti karena yang pertama adalah bahasa pemrograman yang sangat khusus. Yang saya curigai adalah OP bertanya adalah sesuatu di sepanjang baris "Apakah Anda tahu sistem / proses / prosedur yang terbukti yang akan membuat transisi lebih mudah bagi seseorang yang sama sekali tidak mengetahui MATLAB untuk mengatasinya dan menerjemahkan kode ke dalam bahasa pemrograman lain? " Tapi kemudian, itu hanya aku, aku mungkin salah!
Andrea Raimondi
1
Kata harus cocok. Ada dua pendekatan yang bisa Anda ambil. Mengorientasikan halaman dalam mode lansekap dan menyajikan kode MATLAB Anda di sisi kiri dan anotasi Anda di sisi kanan. Atau potret dan beralih antara kode dan eksposisi.
GEL
1
Jika saya adalah pengembang saya ingin tahu yang %memulai komentar, dan kemudian saya ingin komentar jelas ditambahkan ke kode Matlab. Dan izinkan saya kembali dengan pertanyaan tentang hal-hal yang tidak masuk akal bagi saya. Itu akan menjadi yang paling mudah di sekitar.
btilly

Jawaban:

4

masukkan kode MATLAB ke dalam ms-word; ubah font menjadi kurir (monospace) jika itu membantu

sorot setiap baris dan gunakan Sisipkan Komentar (di bawah tab Tinjau di kata 2010) untuk memasukkan penjelasan Anda

pengembang dapat melakukan hal yang sama; kata akan membuat kotak komentar yang berbeda untuk Anda masing-masing

Steven A. Lowe
sumber
Terima kasih Steven, ini adalah jenis jawaban yang saya harapkan. Saya berpikir untuk melakukan ini sebenarnya, tetapi berharap akan ada beberapa metode alternatif yang didedikasikan untuk tugas seperti itu untuk programmer (tidak benar-benar menjadi diri saya sendiri). Terima kasih
gkdsp
@gkdsp: mungkin ada, tetapi kemungkinan semua orang yang menawar proyek ini akan memiliki ms-word
Steven A. Lowe
4
@Stephen A. Lowe: Sebagai orang Linux / Mac, saya benci ketika orang menganggap bahwa saya memiliki kata-ms.
btilly
@ btilly: Kebanyakan orang. Kecuali Anda memiliki alasan filosofis atau moral untuk tidak melakukannya, Anda harus melakukannya juga. Kalau tidak, Anda hanya akan menimbulkan masalah bagi diri Anda sendiri dan (berpotensi) orang lain.
richard
2
@ btilly: buka kantor, dan hentikan sambil tersenyum ;-)
Steven A. Lowe
2

Saya akan menyewa seorang programmer yang sudah akrab dengan Matlab. Lebih sedikit rasa sakit untuk semua orang. Ada banyak dari kita mantan matematikawan yang bekerja dalam pengembangan perangkat lunak :-)

TrojanName
sumber
2
+1: jika pengembang yang Anda miliki tidak mau belajar Matlab, cari pengembang yang lebih baik. Selain itu, jika dia tidak mau belajar Matlab, seberapa baik dia bisa dalam terjemahan?
kevin cline
Saya pasti berpikir akan jauh lebih mudah menemukan seseorang yang sudah mengenal Matlab dan membuat mereka belajar bahasa kedua, daripada sebaliknya. (Kecuali bahasa kedua adalah sesuatu yang bahkan lebih tidak jelas dan sulit dipelajari! LOL)
TrojanName
1

Papan tulis!

Sintaks MATLAB cukup jauh di luar sana dibandingkan dengan bahasa prosedural "normal" (~ = untuk tidak sama dengan !!!!?), Jadi mendokumentasikan setiap baris kode mungkin tidak akan terlalu membantu (transformasi matriks satu-baris pada MATLAB seringkali akan menerjemahkan ke beberapa ratus baris kode C, misalnya).

Mengapa tidak meluangkan waktu mempelajari inti dari fungsionalitas program dengan pengembang di depan papan tulis dengan laptop dengan (atau cetakan) kode yang ada. Dengan begitu Anda bisa terjebak ke dalam bit yang sulit dipahami dari program itu sendiri, bukan sintaks MATLAB.

Jika Anda benar-benar hanya mengharapkan mereka untuk menerjemahkannya ke bahasa lain, Anda tidak ingin mereka harus mengetahui seluk beluk bagaimana MATLAB melakukan prosesnya, mungkin itu tidak akan menerjemahkan dengan baik ke bahasa lain, MATLAB adalah sangat khusus untuk bekerja dengan matriks. Benar-benar Anda hanya perlu mereka tahu bahwa Anda perlu mengalikan matriks A dengan produk B dan melakukan X dengan output.

Ed James
sumber
Saya setuju Ed. Satu baris kode Matlab bisa menjadi heck lebih banyak dalam bahasa lain. Itu sebabnya saya tidak berpikir itu cukup untuk hanya memasok program Matlab. Mengenai papan tulis, itu mengharuskan Anda berada di kota / negara bagian / negara yang sama, yang biasanya tidak mungkin. Juga, saya membuat dokumen untuk perusahaan untuk menawar proyek. Saya perlu menjelaskan apa yang saya ingin mereka lakukan sebelum memutuskan tim atau individu yang akan melakukannya.
gkdsp
1
Oh man. Saya tidak iri dengan Anda, ATAU perusahaan yang memenangkan penawaran.
Kevin
Ah, Anda tidak memperhatikan kurangnya kedekatan fisik dalam pertanyaan, jadi saya minta maaf ini tidak cocok. Aku sudah tugas bekerja dengan MATLAB pada banyak kesempatan dan sejauh yang saya prihatin kode sumber akan efektif berguna kecuali Anda berdua fasih dalam MATLAB untuk memulai dengan dan juga fasih dalam apa kode sebenarnya tidak . Saya pasti akan mencoba menggunakan semacam metode bergambar untuk menyampaikan pesan, seperti diagram alur atau sesuatu. Mungkin sekelompok (saya tidak percaya saya menyarankan ini) diagram aktivitas UML mungkin tepat?
Ed James
1
Sejujurnya, jika saya akan memiliki banyak kode yang diformat, teks dan gambar diselingi saya mungkin akan memilih LaTeX dan mengekspornya ke PDF. Manfaat besar dari LaTeX atas kata adalah bahwa ia benar-benar dapat menangani kode dengan baik (yang saya belum pernah berhasil membuat Word melakukannya dengan benar).
Ed James
1
whitebord + videorecorder
1

Bagaimana dengan menggunakan alat peninjau kode seperti Rietveld atau ReviewBoard

Anda dapat menambahkan komentar dan diskusi yang bukan bagian dari kode Matlab itu sendiri.

Lie Ryan
sumber
0

Saya orang ilmiah yang perlu mendokumentasikan kode Matlab yang kompleks untuk diserahkan kepada pengembang agar dia mengerti dan memprogram dalam bahasa yang berbeda. Di masa lalu, saya telah menggunakan MS Word (menjelaskan setiap langkah program sebagai baris baru dalam sebuah tabel), dan kemudian Excel, tetapi tidak menemukan yang sangat cocok untuk menampilkan kode Matlab saya dan memasukkan komentar secara jelas dan ringkas. cara mendokumentasikannya.

Yah, Word bisa bekerja ... kurasa. Anda menentukan gaya yang berbeda untuk bagian kode yang berbeda (komentar berwarna hijau, kode di ...). Meskipun tidak yakin berapa praktis ini dalam kenyataan. Apa yang salah dengan hanya mengekspornya sebagai HTML dan melayani pengembang dalam pertanyaan itu. Dia selalu dapat menggunakan bantuan online, jika ada masalah, jika dia belum menginstal MATLAB.

Setelah membaca beberapa komentar, izinkan saya mencoba menjelaskan lebih lanjut ... Saya menganggap semua pengembang tahu pseudo-code, tapi saya tidak berasumsi banyak yang tahu kode Matlab. Jadi, jika saya menulis dalam pseudo-code, saya dapat mengabaikan kode Matlab (atau memberikannya untuk referensi, dll.).

Karena Anda menerjemahkan kode MATLAB, dan Anda mengatakan bahwa Anda adalah orang yang ilmiah, dapatkah seseorang berasumsi bahwa persamaan matematika dapat menjadi salah satu alternatif yang layak.

Catat hati-hati ... kadang-kadang fungsi MATLAB yang digunakan BUKAN yang dijelaskan dalam bantuan. Uji kode baru Anda sepanjang jalan.

Benteng
sumber