Documenting or not

There are lots of people talking about the importance of writing code documentation. Some, otherwise, advocate in favor of not documenting at all. These usually say your code must tell the history by itself. I’d like to make my own statement in this matter: I agree with both sides in this discussion.

I love to write code documentation. And sometimes, no matter how much I try to make my code be expressive, I need the support from something more textual. I guess that’s due to my code-writing style. I prefer to use a concise naming to my symbols. Instead of `getAllOrdersFromUser(user)`, I’d rather to use `getOrders(user)`. Unless the context requires a meaningful name, the latter is enough expressive. It says what the function does — gets orders — and based on what — a user. For this example, writing what the function actually does is not so important. I can then omit the doc block. In other cases, though, there are some logic details that can be hidden behind a weak name. For those, a statement on what that piece of code does may be essential for understanding.

Yet, for some projects, I struggle keeping docs up-to-date. This happens especially when I’m writing something that must be deployed ASAP. Or when working with pairs that don’t care about documenting. You should know, real life not always allows you to do everything in the way you want to. If I don’t plan to keep my code and documentation in sync, I do not write a comment that won’t say a thing about the code next to it. It’s preferable having no doc than something that will confuse other dev or even myself.

There is a place in the middle of these two points of view where the day-by-day programming resides. Writing expressively is the better way to coding. But, if you’re adding documentation keep in my mind you must update it constantly as your logic changes.

Advertisements

Regras de ouro para o trabalho remoto

Enquanto escrevo esse post, calculo que fazem mais ou menos 5 anos que eu trabalho remoto. Nesse tempo, tive uma passagem de 1 ano por um emprego in loco, mas nunca deixei de tocar as minhas empresas em paralelo, atendendo os clientes, planejando e executando tudo que fosse necessário.

Trabalhando de casa ou de espaços de coworking, aprendi na prática muita coisa sobre como se relacionar com os clientes e fornecedores, como planejar, acompanhar e executar projetos, e sobre como se virar quando tudo dá errado, ou chega perto disso. Com a minha recente mudança para os Estados Unidos, trabalhar remoto ganhou um significado muito mais importante, porque se antes eu podia ir visitar o cliente ou dar um jeito de passar um dia ou dois por perto dele, essa alternativa não existe mais.

Somando tudo isso, achei que seria útil escrever um texto com algumas dicas de trabalho remoto, mas aí encontrei esse artigo do Diego Eis, no Tableless, e ele já falou tudo aqui, então aproveitem:
6 dicas para se dar bem em freelas e trabalhos remotos

Propel + Symfony2 : Debugando queries em comandos

Quando no ambiente de desenvolvimento, em um projeto baseado no Symfony2, usar o webprofiler na interface web (a partir da barra que fica no rodapé das páginas) é uma mão na roda em várias situações. Mas no console geralmente não temos essa facilidade tão a mão, porém não é impossível acessá-la. Especificamente para as queries executadas através do Propel, é possível usar o seguinte trecho para fins de debug:

$profiler = $this->getContainer()->get('profiler');
$db = $profiler->get('propel');
$db->collect(new \Symfony\Component\HttpFoundation\Request(), new \Symfony\Component\HttpFoundation\Response()); // Stubs, não são usados pelo profiler
var_dump($db->getQueries());

Você pode dar uma olhada na classe Symfony\Bridge\Propel1\DataCollector\PropelDataCollector e conferir os métodos disponíveis.

Outros profilers podem ser acessados através do container, mas como a requisição (request) e a resposta (response) não estão disponíveis no console, pode ser que nem todos funcionem como esperado.

Livro: Código Limpo

Li esse livro faz mais de 1 ano. Havia emprestado para um colega da Gazeta do Povo e, como ele me devolveu essa semana, decidi retornar ao texto por curiosidade — o caminho para casa, de ônibus, é quase sempre dedicado à leitura. Me deparei com um capítulo (17) incrível que eu havia esquecido. Basicamente um resumo de muitos tópicos que o livro trata, com exemplos de código e o que (e não) fazer em cada situação.

Listo abaixo os tópicos relacionados à funções desse capítulo:

Parâmetros em excesso

As funções devem ter um número pequeno de parâmetros. Ter nenhum é melhor. Depois vem um, dois e três. Mais do que isso é questionável e deve-se evitar com preconceito.

Parâmetros de saída

Os parâmetros de saída são inesperados. Os leitores esperam que parâmetros sejam de entrada e não de saída. Se sua função deve alterar o estado de algo, faça-a mudar o do objeto no qual ela é chamada.

Parâmetros lógicos

Parâmetros booleanos explicitamente declaram que a função faz mais de uma coisa. Eles são confusos e devem ser eliminados.

Função morta

Devem-se descartar os métodos que nunca são chamados. Manter pedaços de código mortos é devastador. Não tenha receio de excluir a função. Lembre-se de que o seu sistema de código fonte ainda se lembrará dela.

Caso esse trecho tenha despertado o seu interesse pelo livro, fica uma dica: leia-o no original, em inglês, se você puder. Ou se prepare para uma tradução muito falha e que em alguns pontos requer muito tempo de interpretação e dedução.

cleancode-W800

Martin, Robert C. – Código Limpo: Habilidades Práticas do Agile Software. AltaBooks, 2009.