Moitas guías de estilo e documentación pídennos que escribamos unha breve descrición de cada método e función. Á parte dos beneficios que nos dá documentar o noso código, unha avantaxe de escribir esas descricións é que nos axuda a decatarnos de que podemos facer melloras nese código. Por exemplo, se unha función ten unha descrición difícil de entender, é bastante probable que o código da función tamén sexa excesivamente complicado.
Unha regra que uso acotío é: se a descrición dunha función contén a conxunción “e” ou a conxunción “ou”, case sempre é necesario dividir esa función en varias partes. Unha función debería realizar unha soa operación, non dúas ou tres, e a presenza dunha conxunción na súa descrición é un indicio de que estamos a incumprir esta regra.
—Mimadriña! Cantas cousas fai esta función!
—Pois aínda non chegaches á mellor parte.
Por suposto, o significado de “unha soa operación” depende do nivel de abstracción no que esteades a traballar: nunha parte dun programa, unha operación pode ser “calcular a suma dun array” e noutra parte do mesmo programa pode ser “elaborar un informe de perdas e beneficios”.
Moitas veces combinamos varias operacións nunha soa función por evitar duplicar código. No canto de escribir dúas funcións que son case idénticas, escribimos unha soa función cun parámetro que escolle entre unha operación e a outra. Isto é un erro: o código da función combinada sempre vai ser máis complicado que se tiveramos dúas funcións separadas, e só se vai complicar máis segundo pasa o tempo e temos que facer cambios no código.
Imaxinade o caso totalmente hipotético dun programa para enviar boletíns por email que ten unha función descrita como “programa o envío dun email para despois, ou envíao inmediatamente se a data está baleira”. Ese “ou” da descrición indícanos que deberíamos dividila en dúas funcións distintas.
Cando o fixen —quero dicir, no caso de que ese hipotético programador o fixer—, quedarían dúas funcións case idénticas agás pola derradeira liña. Isto amola a moita xente, pero, por sorte, a solución tórnase evidente cando escribimos as descricións das dúas funcións: a primeira é “prepara un borrador de email e programa o seu envío” e a segunda é “prepara un borrador de email e envíao inmediatamente”.
Como vedes, as dúas descricións conteñen a conxunción “e”, así que é o momento de dividilas en dúas partes outra vez. No final, quedamos con tres funcións: unha que “prepara un borrador de email”, outra que “programa o envío dun borrador” e, finalmente, unha que “envía un borrador inmediatamente”.
Esta hipotética historia que nunca lle pasou a ninguén que coñezades comezou cunha soa función e rematou con tres pero, a cambio, cada unha desas tres funcións realiza unha soa operación, é moito máis pequena e doada de entender e sen duplicación de código.
A próxima vez que, ao escribir unha función, engadades un parámetro para seleccionar unha ou outra operación, desconfiade. Describide o que fai a función. Contén as conxuncións “e” ou “ou”? Será mellor dividila e ter varias funcións simples no canto dunha soa función complicada?
A ilustración desta Folla procede dun gravado de 勝川春章 (Katsukawa Shunshō).
1 comentario