Código de auto-documentação é (geralmente) um absurdo

Olá pessoal!

Antes da publicação traduzida de hoje, apontaremos imediatamente que este texto pretende acompanhar o recente material de discussão " Pare de zeloso com comentários no código ". Ficamos tão impressionados com a discussão que ocorreu lá e com 189 comentários em 19 de julho de 2019, que decidimos dar a palavra a outro autor do portal Medium (Christopher Lane), que polemiza os pontos de princípio com as teses de Brian Norlander, autor do primeiro artigo. Observe que, no original, este artigo foi publicado um mês depois do anterior (16 de maio e 16 de junho), mas coletou quase metade dos aplausos (706 contra 1,5 K no momento da publicação da tradução). Vamos ver o que vai acontecer em Habr ...



Foto tirada em rawpixels.com por Pexels

Li com atenção o excelente artigo de Cindy Cheung sobre documentação técnica e por que os desenvolvedores devem explicar melhor seu próprio código - e devo dizer que concordo totalmente com ele.

Há muito tempo que trabalho nesta sua TI, e minha experiência sugere que existe tanto auto-engano em nossos negócios que desenvolvedores e engenheiros simplesmente não conseguem resistir.

Meu código é auto-documentado - Equívoco

Em teoria, o código de um bom engenheiro deve ser tão claro e legível que simplesmente não precise de documentação.

Você sabe, isso é um absurdo ... como regra.

Por que o "código de auto-documentação" é um absurdo?

Digamos que você escreva um código tão legal quanto Hemingway escreveu em prosa . Talvez o seu código super-duper seja limpo e claro (para outro desenvolvedor). No final, esse código foi escrito por um técnico para um técnico e, por mais limpo e conciso que possa parecer, ele ainda não deve ser lido por não-programadores que poderiam reclamar: “que diabos é tudo isso? quer dizer ?!

Por que eu acho que o código de auto-documentação não faz sentido? Deixe-me explicar em detalhes.

Razão 1: a programação está cheia de todos os tipos de truques que não são auto-documentados.

Só porque a maioria das pessoas, incluindo desenvolvedores, não são carros. Sim, provavelmente vou ler seu código, entender os nomes de seus métodos e classes e até entender exatamente o que você faz em cada método.

Mas o código está escrito para carros. Eles entendem muito melhor do que nós o que fazer com isso e, para descrevê-lo, temos linguagens de programação. Você precisa se comunicar com as pessoas em uma linguagem mais humana para que uma pessoa possa entender o que o seu software faz.

Há uma grande diferença entre "ler o código e ver o que está acontecendo nele" e a documentação. É possível escrever no código com todos os detalhes, o que é feito nele, mas pode ser chamado de "auto-documentação" nesse caso? Acho que todo mundo entende que é impossível.

Considere o seguinte blob simples em C #. Eu leio o arquivo, obtenho seu conteúdo e, em seguida, obtenho a codificação de arquivo usando o 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:

, – . , (- , ), .

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

,