Le code d'auto-documentation est (généralement) un non-sens

Bonjour à tous!

Avant la publication de la traduction d'aujourd'hui, nous signalerons immédiatement que ce texte est destiné à faire suite au récent document de discussion « Arrêtez de faire preuve de zèle avec des commentaires dans le Code ». Nous avons été tellement impressionnés par la discussion qui s'y est déroulée et par 189 commentaires au 19/07/2019, que nous avons décidé de donner la parole à un autre auteur du portail Medium (Christopher Lane), qui polémique sur les points de principe avec les thèses de Brian Norlander, l'auteur du premier article. A noter que dans l'original, cet article a été publié un mois plus tard que le précédent (16 mai et 16 juin), mais il a recueilli près de la moitié des applaudissements (706 contre 1,5 K au moment de la publication de la traduction). Voyons ce qui va se passer sur Habr ...



Photo prise sur rawpixels.com par Pexels

J'ai lu attentivement l'excellent article de Cindy Cheung sur la documentation technique et pourquoi les développeurs devraient mieux expliquer leur propre code - et je dois dire que je suis entièrement d'accord avec lui.

Je fais beaucoup de temps dans cette informatique, et mon expérience suggère qu'il y a une telle auto-illusion dans notre entreprise que les développeurs et les ingénieurs ne peuvent tout simplement pas résister.

Mon code est auto-documenté - Idée fausse

En théorie, le code d'un bon ingénieur doit être si clair et lisible qu'il n'a tout simplement pas besoin de documentation.

Vous savez, c'est un non-sens ... en règle générale.

Pourquoi le "code auto-documenté" est-il absurde?

Disons que vous écrivez du code aussi cool que Hemingway a écrit de la prose . Peut-être que votre code super-duper est propre et clair (pour un autre développeur). En fin de compte, ce code a été écrit par un technicien pour un technicien, et peu importe la netteté et la concision de votre code, il n'est toujours pas destiné à être lu par des non-programmeurs qui pourraient grogner: «Qu'est-ce que l'enfer est tout cela signifie?! "

Pourquoi est-ce que je pense que le code auto-documenté est un non-sens? Permettez-moi de vous expliquer en détail.

Raison 1: la programmation regorge de toutes sortes de trucs qui ne sont pas auto-documentés.

Tout simplement parce que la plupart des gens, y compris les développeurs, ne sont pas des voitures. Oui, très probablement, je vais parcourir votre code, je comprendrai les noms de vos méthodes et classes, je comprendrai même exactement ce que vous faites dans chaque méthode.

Mais le code est écrit POUR les voitures. Ils comprennent beaucoup mieux que nous ce qu'il faut en faire, et pour leur décrire, nous avons des langages de programmation. Vous devez communiquer avec les gens dans un langage plus humain afin qu'une personne puisse comprendre ce que fait votre logiciel.

Il y a une très grande différence entre «lire le code et voir ce qui s'y passe» et la documentation. Il est possible d'écrire dans le code avec tous les détails ce qui y est fait, mais peut-il être appelé "auto-documentation" dans ce cas? Je pense que tout le monde comprend que c'est impossible.

Considérez le blob simple suivant en C #. Je lis le fichier, j'obtiens son contenu, puis j'obtiens l'encodage du fichier à l'aide de 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:

, – . , (- , ), .

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

,