📷 💪🏿 🗽 自记录代码（通常）是胡说八道 📗 😟 ♦️

大家好！

预期今天会有翻译版出版，因此我们立即注意到，该文本旨在作为近期讨论材料“ 在代码中停止带有评论的热忱 ”的后续措施。截止到2019年7月19日，我们对其中的讨论印象深刻，并发表了189条评论，以至于我们决定请媒体门户网站（Christopher Lane）的另一位作者发言，他对第一篇文章的作者Brian Norlander的论点持偏见。请注意，本文的原文比上一篇（5月16日和6月16日）晚发布了一个月，但它收录了几乎掌声（在翻译出版时为706，对应1.5 K）。让我们看看在哈伯上会发生什么...

Pexels从rawpixels.com拍摄的照片

我仔细阅读了Cindy Cheung关于技术文档的出色文章，以及为什么开发人员应该更好地解释自己的代码-我必须说我完全同意。

我在您的IT部门工作了很长时间，我的经验表明，我们业务中存在这样的自我欺骗，开发人员和工程师根本无法抗拒。

我的代码是自我记录的-误解

从理论上讲，优秀工程师的代码应如此清晰易读，以至于不需要任何文档。

你知道，这是胡说八道...通常。

为什么“自记录代码”是胡说八道？

假设您编写的代码像海明威写的散文一样酷。也许您的超级Duper代码是干净清晰的（对另一个开发人员而言）。最后，该代码是由一个技术人员为一个技术人员编写的，无论您的代码看起来多么简洁明了，仍然不适合那些可能抱怨的非程序员阅读：“这到底是什么？是什么意思？！

为什么我认为自记录代码完全是胡说？让我详细解释。

原因1：编程中充满了各种无法自我记录的技巧。

仅因为包括开发人员在内的大多数人都不是汽车。是的，很可能我会遍历您的代码，了解您的方法和类的名称，甚至了解您在每种方法中的确切用途。

但是代码是为汽车编写的。他们比我们更了解如何使用它，并且为了向他们描述它，我们拥有编程语言。您需要使用更加人性化的语言与人们交流，以便人们可以理解您的软件的功能。

“阅读代码并查看其中发生了什么”与文档之间有很大的区别。可以在代码中写下所有细节，但在这种情况下可以称为“自我记录”吗？我认为所有人都知道这是不可能的。

考虑以下C＃中的简单blob。我读取了文件，获取了文件的内容，然后使用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:

, – . , (- , ), .

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

,

自记录代码（通常）是胡说八道

为什么“自记录代码”是胡说八道？

1:

2:

3: (Ubiquitous Language)

4:

More articles: