स्व-दस्तावेजीकरण कोड (आमतौर पर) बकवास है

सभी को नमस्कार!

आज के अनुवादित प्रकाशन की प्रत्याशा में, हम तुरंत ध्यान देंगे कि यह पाठ हालिया चर्चा सामग्री " कोड में टिप्पणियों के साथ उत्साही " के रूप में अनुवर्ती है। 19 जुलाई, 2019 तक हुई चर्चा और 189 टिप्पणियों से हम इतने प्रभावित हुए कि हमने मीडियम पोर्टल (क्रिस्टोफर लेन) से एक अन्य लेखक को मंजिल देने का फैसला किया, जो पहले लेख के लेखक ब्रायन नॉरलैंडर के थ्रेड्स के साथ सिद्धांत के बिंदुओं पर ध्रुवीकरण करता है। ध्यान दें कि मूल में, यह लेख पिछले एक (16 मई और 16 जून) की तुलना में एक महीने बाद प्रकाशित किया गया था, लेकिन इसने लगभग आधे तालियों (अनुवाद के प्रकाशन के समय 1.5 K के खिलाफ 706) एकत्र किया। आइए देखते हैं क्या होगा ह्रोब पर ...



Pexels द्वारा rawpixels.com से लिया गया फोटो

मैं तकनीकी दस्तावेज पर सिंडी चेउंग द्वारा उत्कृष्ट लेख को ध्यान से पढ़ता हूं और डेवलपर्स को अपने कोड को बेहतर ढंग से क्यों बताना चाहिए - और मुझे यह कहना चाहिए कि मैं इससे पूरी तरह सहमत हूं।

मैं आपके इस IT में एक लंबे समय से नरक कर रहा हूं, और मेरे अनुभव से पता चलता है कि हमारे व्यवसाय में ऐसे आत्म-धोखे हैं, जिन्हें डेवलपर्स और इंजीनियर बस विरोध नहीं कर सकते हैं।

मेरा कोड स्व-दस्तावेजीकरण है - गलत धारणा

सिद्धांत रूप में, एक अच्छे इंजीनियर का कोड इतना स्पष्ट और पठनीय होना चाहिए कि उसे किसी भी दस्तावेज की आवश्यकता न हो।

तुम्हें पता है, यह बकवास है ... एक नियम के रूप में।

"स्व-दस्तावेजीकरण कोड" बकवास क्यों है?

मान लीजिए कि आप कोड लिखते हैं जैसे कि हेमिंग्वे ने गद्य लिखा था । शायद आपका सुपर-डुपर कोड साफ और स्पष्ट है (दूसरे डेवलपर के लिए)। अंत में, यह कोड एक तकनीकी विशेषज्ञ के लिए एक तकनीकी विशेषज्ञ द्वारा लिखा गया था, और कोई फर्क नहीं पड़ता कि आपका कोड कितना साफ और संक्षिप्त लग सकता है, यह अभी भी गैर-प्रोग्रामर द्वारा पढ़ा जाने का इरादा नहीं है, जो गड़गड़ाहट कर सकते हैं: "क्या यह सब है मतलब! ”

मुझे क्यों लगता है कि स्व-दस्तावेजीकरण कोड सभी बकवास है? मुझे विस्तार से बताएं।

कारण 1: प्रोग्रामिंग में बहुत सारी तरकीबें हैं जो स्व-दस्तावेजीकरण नहीं हैं

सिर्फ इसलिए कि डेवलपर्स सहित ज्यादातर लोग कार नहीं हैं। हां, सबसे अधिक संभावना है कि मैं आपके कोड के माध्यम से जाऊंगा, मुझे आपके तरीकों और कक्षाओं के नाम समझ में आएंगे, मैं यह भी समझ सकता हूं कि आप प्रत्येक विधि में वास्तव में क्या करते हैं।

लेकिन कोड कारों के लिए लिखा गया है। वे हमसे बेहतर समझते हैं कि इसके साथ क्या करना है, और इसका वर्णन करने के लिए, हमारे पास प्रोग्रामिंग भाषाएं हैं। आपको अधिक मानवीय भाषा में लोगों के साथ संवाद करने की आवश्यकता है ताकि एक व्यक्ति यह समझ सके कि आपका सॉफ्टवेयर क्या करता है।

"कोड को पढ़ने और इसमें क्या हो रहा है" और प्रलेखन देखने के बीच एक बहुत बड़ा अंतर है। सभी विवरणों के साथ कोड में लिखना संभव है, इसमें क्या किया गया है, लेकिन क्या इसे इस मामले में "स्व-दस्तावेजीकरण" कहा जा सकता है? मुझे लगता है कि हर कोई समझता है कि यह असंभव है।

सी # में निम्नलिखित सरल बूँद पर विचार करें। मैंने फ़ाइल पढ़ी, उसकी सामग्री प्राप्त की, और फिर स्ट्रीमराइडर का उपयोग करके फ़ाइल एन्कोडिंग प्राप्त की।

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:

, – . , (- , ), .

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

,