Estou usando um patch recente contribuído pelo Rafael para esclarecer um pouco como contribuir com patches. Essa thread vai se transformar em algum guia na documentação de desenvolvimento no wiki.
Como todos sabem, grande parte do código do i-Educar não se encontra sobre padrões de codificação concisos. A identação feita hora por <tab> hora por espaço é prova clara disso.
Qual é o problema nisso?
Qualquer software em que mais de uma pessoa trabalha deve ter padrões de codificação claros, para que todos contribuam com código seguindo a mesma forma. Isso é importante já que a forma do código é um item importante para o entendimento de um trecho por outros programadores.
Outro item importante nisso é para o uso de ferramentas de desenvolvimento, como o diff. Quando temos um software com versionamento de código-fonte, podemos visualizar através de seu histórico todas as alterações feitas. Quando não aplicamos padrões de codificação, visualizar essas mudanças fica mais difícil. Exemplos:
- O diff do Trac. Quando substituímos um <tab> de identação pelo equivalente em espaços, o diff do Trac mostra uma identação menor.
- IDEs com configuração para apagar espaços adicionais nos finais de linhas. Ao fazer isso, quando usamos o diff, acabamos por visualizar diversas linhas em que apenas um espaço adicional foi apagado.
Claro que é fácil solicitar ao diff que não mostre mudanças de espaços (basta usar diff -Nur ao invés de -Naur) mas isso tem a capacidade de dar mais confusão do que solução.
Qual é a aproximação correta em um software legado, então? Não existe. O que podemos fazer são pequenas adequações para só então corrigirmos um bug ou implementarmos uma melhoria no código.
No i-Educar, para preservar o histórico de mudanças no código, tenho recorrido a alguns passos metódicos:
- Minha IDE está sempre configurada para apagar espaços em brancos no final da linha. Seja quando uso o Eclipse, TextMate ou Vim
- Sempre, sempre passo o código para os padrões de codificação do i-Educar antes de modificá-lo. É por isso que tem tantos commits no repositório com a frase "Refactoring para coding standards". Dessa forma, o commit com a correção do código posterior irá ficar muito mais simples de entender. Outro benefício é o de padronizar o código. Matamos 2 coelhos numa cajadada só.
- Somente então faço a correção do código. Dois commits de exemplo são: 598 e 599.
O passo 2 é muito monótono quando estamos trabalhando em um código legado mas é um mal necessário. Dessa forma, aos poucos, damos padrão ao código. A ideia é ir padronizando enquanto corrigimos e implementamos melhorias. Café (forte, com pouco açúcar) e rock (pop, indie, britânico, hard, metal, nü... não importa, que seja rock) são recomendados enquanto se faz isso.
Como não iremos dar permissão de escrita no repositório a torto e a direito, a contribuição tem que ser via patch. No wiki temos o exemplo através de svn diff, mas esse método fica um pouco difícil quando você executa o passo 2 e depois o 3. Como dica, recomendo usar o git (através do git svn), que permite criar um repositório local, com branches locais. Assim você faz as suas correções em um branch local e depois sincronizar o seu repositório com as alterações do repositório oficial.
Por fim, ao contribuir o patch via Trac, não marque o ticket como encerrado. Só será encerrado quando este for aplicado, testado e commitado (êta neologismo). Encerrar o ticket antes da hora pode resultar em eu não o vê-lo e ficar esquecido até 2012. :)
Observação: use, por enquanto, o branch RegrasAvaliacao para criar os patches. Um problema de infra do portal não está possibilitando fazer o merge desse branch em trunk/. Quando o problema for solucionado, passaremos a usar trunk/ como árvore de desenvolvimento novamente.
Autor: Eriksen Costa
55 comentários