Selbstdokumentierender Code ist (normalerweise) Unsinn

Hallo allerseits!

Vor der heutigen übersetzten Veröffentlichung werden wir sofort darauf hinweisen, dass dieser Text als Nachfolger des jüngsten Diskussionsmaterials " Stop Zealous with Comments in the Code " gedacht ist. Wir waren so beeindruckt von der Diskussion, die sich dort abspielte, und 189 Kommentaren zum 19. Juli 2019, dass wir beschlossen, einem anderen Autor aus dem Medium-Portal (Christopher Lane) das Wort zu erteilen, der mit Thesen von Brian Norlander, dem Autor des ersten Artikels, die Grundsätze polemisiert. Beachten Sie, dass dieser Artikel im Original einen Monat später als der vorherige (16. Mai und 16. Juni) veröffentlicht wurde, aber fast die Hälfte des Applaus sammelte (706 gegen 1,5 K zum Zeitpunkt der Veröffentlichung der Übersetzung). Mal sehen, was auf Habr passieren wird ...



Foto von rawpixels.com von Pexels genommen

Ich habe den ausgezeichneten Artikel von Cindy Cheung über die technische Dokumentation sorgfältig gelesen und erklärt, warum Entwickler ihren eigenen Code besser erklären sollten - und ich muss sagen, dass ich dem vollkommen zustimme.

Ich habe verdammt lange Zeit in Ihrer IT gearbeitet, und meine Erfahrung zeigt, dass es in unserem Geschäft eine solche Selbsttäuschung gibt, der Entwickler und Ingenieure einfach nicht widerstehen können.

Mein Code ist selbstdokumentierend - Missverständnis

Theoretisch sollte der Code eines guten Ingenieurs so klar und lesbar sein, dass er einfach keine Dokumentation benötigt.

Weißt du, das ist Unsinn ... in der Regel.

Warum ist "selbstdokumentierender Code" Unsinn?

Angenommen, Sie schreiben Code so cool, wie Hemingway Prosa geschrieben hat . Vielleicht ist Ihr Super-Duper-Code sauber und klar (für einen anderen Entwickler). Am Ende wurde dieser Code von einem Technikfreak für einen Technikfreak geschrieben, und egal wie sauber und prägnant Ihr Code auch sein mag, er soll immer noch nicht von Nicht-Programmierern gelesen werden, die meckern könnten: „Was zum Teufel ist das alles? meine ?! "

Warum halte ich selbstdokumentierenden Code für Unsinn? Lassen Sie mich im Detail erklären.

Grund 1: Die Programmierung ist voll von Tricks aller Art, die sich nicht selbst dokumentieren.

Nur weil die meisten Menschen, einschließlich der Entwickler, keine Autos sind. Ja, höchstwahrscheinlich werde ich Ihren Code durchgehen, ich werde die Namen Ihrer Methoden und Klassen verstehen, ich werde sogar verstehen, was genau Sie in jeder Methode tun.

Aber der Code ist für Autos geschrieben. Sie verstehen viel besser als wir, was sie damit anfangen sollen, und um es ihnen zu beschreiben, haben wir Programmiersprachen. Sie müssen mit Menschen in einer menschlicheren Sprache kommunizieren, damit eine Person verstehen kann, was Ihre Software tut.

Es gibt einen sehr großen Unterschied zwischen dem „Lesen des Codes und dem Sehen, was darin passiert“ und der Dokumentation. Es ist möglich, mit allen Details in den Code einzutragen, was darin gemacht wird, aber kann es in diesem Fall als "selbstdokumentierend" bezeichnet werden? Ich denke, jeder versteht, dass es unmöglich ist.

Betrachten Sie den folgenden einfachen Blob in C #. Ich lese die Datei, erhalte ihren Inhalt und erhalte dann die Dateicodierung mit 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:

, – . , (- , ), .

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

,