Kode yang didokumentasikan sendiri adalah omong kosong (biasanya)

Halo semuanya!

Sebelum publikasi yang diterjemahkan hari ini, kami akan segera menunjukkan bahwa teks ini dimaksudkan sebagai tindak lanjut dari bahan diskusi baru-baru ini, " Hentikan Zelous dengan Komentar dalam Kode ." Kami sangat terkesan dengan diskusi yang berlangsung di sana dan 189 komentar pada 19/07/2019, bahwa kami memutuskan untuk memberikan dasar kepada penulis lain dari portal Medium (Christopher Lane), yang polemik pada poin-poin prinsip dengan tesis Brian Norlander, penulis artikel pertama. Perhatikan bahwa dalam aslinya, artikel ini diterbitkan sebulan lebih lambat dari yang sebelumnya (16 Mei dan 16 Juni), tetapi ia mengumpulkan hampir setengah tepuk tangan (706 melawan 1,5 K pada saat publikasi terjemahan). Mari kita lihat apa yang akan terjadi pada Habr ...



Foto diambil dari rawpixels.com oleh Pexels

Saya dengan cermat membaca artikel yang sangat bagus dari Cindy Cheung tentang dokumentasi teknis dan mengapa pengembang harus menjelaskan kode mereka sendiri dengan lebih baik - dan saya harus mengatakan bahwa saya sepenuhnya setuju dengan itu.

Saya sudah melakukan hal yang sangat lama dalam bidang TI ini untuk Anda, dan pengalaman saya menunjukkan bahwa ada penipuan diri sendiri dalam bisnis kami sehingga para pengembang dan insinyur tidak bisa menolaknya.

Kode saya mendokumentasikan diri sendiri - Kesalahpahaman

Secara teori, kode insinyur yang baik harus sangat jelas dan mudah dibaca sehingga tidak memerlukan dokumentasi apa pun.

Kau tahu, ini omong kosong ... sebagai aturan.

Mengapa "kode dokumentasi sendiri" tidak masuk akal?

Katakanlah Anda menulis kode sekeren prosa Hemingway . Mungkin kode super-duper Anda bersih dan jelas (untuk pengembang lain). Pada akhirnya, kode ini ditulis oleh teknisi untuk teknisi, dan tidak peduli seberapa bersih dan ringkas kode Anda, masih tidak dimaksudkan untuk dibaca oleh non-programmer yang mungkin menggerutu: “apa-apaan ini semua jahat?! ”

Mengapa saya menganggap kode dokumentasi diri itu omong kosong? Biarkan saya jelaskan secara mendetail.

Alasan 1: Pemrograman penuh dengan semua jenis trik yang tidak mendokumentasikan diri sendiri.

Hanya karena kebanyakan orang, termasuk pengembang, bukan mobil. Ya, kemungkinan besar saya akan membaca kode Anda, saya akan mengerti nama-nama metode dan kelas Anda, saya bahkan akan mengerti apa yang sebenarnya Anda lakukan di setiap metode.

Tetapi kodenya ditulis UNTUK mobil. Mereka mengerti jauh lebih baik daripada kita apa yang harus dilakukan dengan itu, dan untuk menggambarkannya kepada mereka, kita memiliki bahasa pemrograman. Anda perlu berkomunikasi dengan orang-orang dalam bahasa yang lebih manusiawi sehingga seseorang dapat memahami apa yang dilakukan perangkat lunak Anda.

Ada perbedaan yang sangat besar antara "membaca kode dan melihat apa yang terjadi di dalamnya" dan dokumentasi. Dimungkinkan untuk menuliskan dalam kode dengan semua perincian apa yang dilakukan di dalamnya, tetapi bisakah itu disebut “mendokumentasikan diri” dalam kasus ini? Saya pikir semua orang mengerti bahwa itu tidak mungkin.

Pertimbangkan gumpalan sederhana berikut di C #. Saya membaca file, mendapatkan isinya, dan kemudian mendapatkan pengkodean file menggunakan StreamReader.

var fileContents = “”;
Encoding fileEncoding; using (var reader = new StreamReader(filePath, Encoding.Default,  true))
 {
   reader.Peek(); 
   fileEncoding = reader.CurrentEncoding;
   fileContents = reader.ReadToEnd();
 }

StreamReader, , ? … , ?

reader.Peek();

, , . , ? - 10 , .

reader.Peek(); //     ,    .

, , . , , . , , , .

2:

BASH BAT, , , , . . , .

, , – -, , -.

, -, . , - API-, -. - API- , , , , - . «» . « » - «, , ». , - «».

, , , . , , , , , .

3:

jquery, API.

var myURL="https://some.url/path?access_token=my_token";

$.ajax({
    url: myURL+"&callback=?",
    data: "message="+someOtherData,
    type: 'POST',
    success: function (resp) {
        alert(resp);
    },
    error: function(e) {
        alert('Error: '+e);
    }  
});

…

, , - . jquery . , , - -, , -. .

, , , , . , . , , .

.

?

, , .

1:

, ? ?! !

, « ». , – .

• API /someurl/object/{id}
• API {id} ( int), .
• null, API HTTP- 404 ( ). API- .
• — NOT null, API JSON HTTP- 200 (OK).

, , , - . , : , , .

2:

- , , , , «», , .
websequencediagrams.com, – .

title Service one to service two
Service two requester -> Service two http client: Get Contract
Service two http client -> Service one REST API: GET /api/contracts/{123}
Service one REST API -> Service one app logic: get Contract with id 123
Service one app logic -> Service one REST API: Contract
Service one REST API -> Service one REST API: Serialise to JSON / XML / etc.
Service one REST API -> Service two http client: Serialised data
Service two http client -> Service two http client : Deserialise to Contract
Service two http client -> Service two requester: Contract

,



!

, – , . - - , . , .

3: (Ubiquitous Language)

, – DDD (- ), , . , , , , .

, , , , , , .

/// <summary>
///        /  ,            
/// settings
/// </summary>
public interface ICustomer
{
     Task<AuthenticationResult> Login(string username, EncryptedString password);
     Task Logout();
     Task<CustomerProfileInformation> GetMyProfile();
     Task SaveMyProfile(CustomerProfileInformation);
     Task<CustomerSettings> GetMySettings();
     Task SaveMySettings(CustomerSettings);

, , , .

4:

, – . , (- , ), .

, , , . ( ). , , , , .

,