El código de autodocumentación es (generalmente) sin sentido

Hola a todos!

Antes de la publicación traducida de hoy, señalaremos de inmediato que este texto pretende ser un seguimiento del material de discusión reciente, " Stop Zealous with Comments in the Code ". Nos impresionó tanto la discusión que se desarrolló allí y 189 comentarios a partir del 19 de julio de 2019, que decidimos cederle la palabra a otro autor del portal Medium (Christopher Lane), que se conmociona por los principios con las tesis de Brian Norlander, el autor del primer artículo. Tenga en cuenta que, en el original, este artículo se publicó un mes más tarde que el anterior (16 de mayo y 16 de junio), pero reunió casi la mitad de los aplausos (706 contra 1.5 K en el momento de la publicación de la traducción). Veamos qué pasará en Habr ...



Foto tomada de rawpixels.com por Pexels

Leí cuidadosamente el excelente artículo de Cindy Cheung sobre documentación técnica y por qué los desarrolladores deberían explicar mejor su propio código, y debo decir que estoy completamente de acuerdo con él.

He estado haciendo mucho tiempo en esta TI tuya, y mi experiencia sugiere que hay tal autoengaño en nuestro negocio que los desarrolladores e ingenieros simplemente no pueden resistirse.

Mi código es autodocumentado - Concepto erróneo

En teoría, el código de un buen ingeniero debe ser tan claro y legible que simplemente no necesita ninguna documentación.

Sabes, esto no tiene sentido ... como regla.

¿Por qué no tiene sentido el "código autodocumentado"?

Digamos que escribes un código tan genial como Hemingway escribió en prosa . Quizás su código súper duper esté limpio y claro (para otro desarrollador). Al final, este código fue escrito por un técnico para un técnico, y no importa cuán limpio y conciso pueda parecer su código, todavía no está destinado a ser leído por personas que no sean programadores que puedan quejarse: "qué demonios es todo esto significa ?!

¿Por qué creo que el código autodocumentado no tiene sentido? Déjame explicarte en detalle.

Razón 1: la programación está llena de todo tipo de trucos que no se documentan automáticamente.

Solo porque la mayoría de las personas, incluidos los desarrolladores, no son automóviles. Sí, lo más probable es que revise su código, entienda los nombres de sus métodos y clases, incluso entiendo qué hace exactamente en cada método.

Pero el código está escrito para automóviles. Entienden mucho mejor que nosotros qué hacer con él, y para describirlo, tenemos lenguajes de programación. Necesita comunicarse con personas en un lenguaje más humano para que una persona pueda entender lo que hace su software.

Hay una gran diferencia entre "leer el código y ver lo que está sucediendo en él" y la documentación. Es posible escribir en el código con todos los detalles lo que se hace en él, pero ¿se puede llamar "autodocumentado" en este caso? Creo que todos entienden que es imposible.

Considere el siguiente blob simple en C #. Leo el archivo, obtengo su contenido y luego obtengo la codificación del archivo usando 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:

, – . , (- , ), .

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

,