Linus Torvalds nos enseña lo que es buen gusto al comentar código

Si lo dijera otro nos daría igual, pero las rabietas de Torvalds siempre trascienden más allá de las listas de desarrollo del kernel y quizás porque no somos nosotros quienes las sufrimos, nos ilustran y divierten por igual.

Uno de los temas recurrentes en cualquier entrevista realizada a Linus es lo que el entiende por buen gusto a la hora de escribir código en C ,que es el lenguaje de programación sobre el que se construye el núcleo de nuestro sistema.

Un buen gusto que llega también a la hora de comentar el código creado. Y sino que se lo digan a los creadores de un parche en el kernel relacionado con el algoritmo de cifrado SHA-256, para los que Torvalds tiene un cariñoso mensaje:

Can we please get rid of the brain-damaged stupid networking comment
syntax style, PLEASE?

If the networking people cannot handle the pure awesomeness that is a
balanced and symmetric traditional multi-line C style comments, then
instead of the disgusting unbalanced crap that you guys use now,
please just go all the way to the C++ mode.

Además de recomendar a la gente de redes que elimine su estúpido y dañado cerebralmente estilo de comentarios, Linus recuerda cual es la sintaxis recomendada en C, con varios ejemplos, que el considera visualmente balanceados:

(a)
/* This is a comment *./

(b)
/*
* This is also a comment, but it can now be cleanly
* split over multiple lines
*/

(c)
// This can be a single line. Or many. Your choice.

Este es un estilo al que considera pasable aunque no propio del kernel:

/* This is an alternate multi-line format
that isn't horrible, but not kernel style */

Y por último THE HORROR, lo que nunca hay que hacer, en un par de ejemplos:

(no)
/* This is disgusting drug-induced
* crap, and should die
*/

(no-no-no)
/* This is also very nasty
* and visually unbalanced */

Este último (el de no-no-no) es del que están abusando últimamente los desarrollares encargados del asunto de networking en el kernel. Aunque con LSD y usando C ++ (al que Linus le tiene bastante manía) todo se ve mejor:

I’m not even going to start talking about the people who prefer to
«box in» their comments, and line up both ends and have fancy boxes of
stars around the whole thing. I’m sure that looks really nice if you
are out of your mind on LSD, and have nothing better to do than to
worry about the right alignment of the asterisks.

I’d be happy to start moving the whole kernel over to the C++ style,
it’s been many many years since we had compatibility issues and we are
all used to it by now, even if we weren’t all fans originally.

Me gustaría recordar también algo de lo que dice el manual de estilo del kernel, respecto de como comentar el código:

Comentarios son buenos, pero también existe un peligro en sobre-comentar.

En general, quieres que tus comentarios digan lo que tu código hace, no como. Además, trata de evitar poner comentarios dentro del cuerpo de una función: si la función es tan compleja que necesitas comentar por separado partes de ella, probablemente deberías volver al capítulo anterior (en el se recomiendan funciones de pequeño tamaño y que hagan solo una cosa). Tu puedes hacer notas o comentarios sobre algo particularmente inteligente (o feo), pero trata de evitar excesos. En su lugar pon los comentarios en el head de la función.

Siempre se aprende de Linus Torvalds, aunque estaría bien que alguna vez fuera el que recibiera su propia medicina y se le corrigiera de forma también rotunda, más que nada para comprobar su reacción. Difícil de ver, dado que su función de líder hace tiempo que no incluye crear código.

A todo esto comentarios que la salida de Linux 4.7 se va a retrasar una semanita, por culpa de un par de regresiones pendientes y el periodo vacacional.

Imagen | The Linux Foundation (CC BY-NC 2.0)