رمز التوثيق الذاتي (عادة) هراء

مرحبا بالجميع!

قبل النشر المترجم اليوم ، سنشير على الفور إلى أن هذا النص يهدف إلى متابعة مادة المناقشة الأخيرة ، " أوقف الغيرة مع التعليقات في المدونة ". لقد تأثرنا كثيراً بالمناقشات التي تكشفت هناك و 189 تعليقًا اعتبارًا من 19 يوليو 2019 ، حتى قررنا إعطاء الكلمة لمؤلف آخر من البوابة المتوسطة (Christopher Lane) ، الذي يتناقش حول النقاط الأساسية مع أطروحات برايان نورلاندر ، مؤلف المقال الأول. لاحظ أنه في الأصل ، تم نشر هذا المقال بعد شهر واحد من السابق (16 مايو و 16 يونيو) ، لكنه جمع ما يقرب من نصف التصفيق (706 ضد 1.5 K في وقت نشر الترجمة). دعونا نرى ما سيحدث على هبر ...



الصورة مأخوذة من rawpixels.com بواسطة Pexels

قرأت بعناية المقالة الممتازة التي أعدتها سيندي تشيونغ حول الوثائق التقنية ولماذا يجب على المطورين شرح رمزهم بشكل أفضل - ويجب أن أقول أنني أتفق معه تمامًا.

لقد كنت أقوم بجحيم منذ فترة طويلة في مجال تكنولوجيا المعلومات الخاص بك ، وتشير تجربتي إلى أن هناك خداعًا ذاتيًا في أعمالنا لا يمكن للمطورين والمهندسين أن يقاوموه.

الكود هو توثيق ذاتي - سوء فهم

من الناحية النظرية ، يجب أن تكون مدونة المهندس الجيد واضحة وقابلة للقراءة بحيث لا تحتاج إلى أي وثائق.

كما تعلمون ، هذا هراء ... كقاعدة عامة.

لماذا "رمز التوثيق الذاتي" هراء؟

دعنا نقول أنك تكتب رمزًا رائعًا كما كتب همنغواي النثر . ربما لديك رمز المخادع السوبر نظيفة وواضحة (لمطور آخر). في النهاية ، تمت كتابة هذا الرمز بواسطة فني للحصول على فني ، وبغض النظر عن مدى نظافة وموجز الرمز الخاص بك ، لا يزال من غير المقصود أن يقرأه غير المبرمجين الذين يمكن أن يتذمروا: "ماذا بحق الجحيم هو كل هذا يعني؟! "

لماذا أعتقد أن رمز التوثيق الذاتي هو كل هذا هراء؟ اسمحوا لي أن أشرح بالتفصيل.

السبب 1: البرمجة مليئة بجميع أنواع الحيل التي لا توثق نفسها بنفسها.

فقط لأن معظم الناس ، بما في ذلك المطورين ، ليسوا سيارات. نعم ، على الأرجح سوف أتطرق إلى التعليمات البرمجية الخاصة بك ، وسأفهم أسماء أساليبك وفصولك ، حتى أنني أفهم ما تفعله بالضبط في كل طريقة.

لكن الرمز مكتوب للسيارات. إنهم يفهمون أكثر مما ينبغي لنا أن نفعله به ، ومن أجل وصفه لهم ، لدينا لغات برمجة. تحتاج إلى التواصل مع أشخاص بلغة أكثر إنسانية حتى يتمكن الشخص من فهم ما يفعله البرنامج.

هناك فرق كبير بين "قراءة الكود ورؤية ما يحدث فيه" والوثائق. من الممكن أن تدون في الكود بكل التفاصيل ما يجري ، لكن هل يمكن أن يسمى "التوثيق الذاتي" في هذه الحالة؟ أعتقد أن الجميع يفهمون أن هذا مستحيل.

النظر في النقطة التالية بسيطة في C #. قرأت الملف ، وحصلت على محتوياته ، ثم حصلت على ترميز الملف باستخدام 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:

, – . , (- , ), .

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

,