Convenções de código do Projeto GOD

Os nomes de pacotes, classes, commits, métodos, variáveis e comentários do projeto devem estar em inglês.

 

Pacotes:

Pacotes (ou categorias) são as estruturas que contém as classes de um projeto em Smalltalk. 

O pacote principal deve ser nomeado como GOD + Package. Ex: GODSocialNetIO

Cada grupo deve criar todas as classes principais do seu projeto dentro de um único pacote.

Os testes devem ser criados em um pacote separado contendo a mesma estrutura de nome acrescido do termo Tests no final.

Ex: GODSocialNetIOTests

Da mesma forma, classes de tratamento de exceção podem ser agrupadas em um pacote separado, com o nome do projeto seguido do termo Exceptions no final.

Ex: GODSocialNetIOExceptions

 

Classes:

As classes do projeto devem conter as iniciais do nome do pacote do projeto em letras maiúsculas. As iniciais devem conter entre 2 e 4 letras.

Ex: Para o pacote GODSocialNetIO, exemplos de nome de classe são SNETFetcher ou SNIOFetcher. Adotem uma sigla, e usem-na sempre.

Já a classe de testes deve conter o termo Test no final do nome da classe, ex: SNETFetcherTest

 

Commits:

Na primeira vez que for salvar o seu projeto no Monticello, Squeak pede as iniciais do autor do commit. Coloque as iniciais do seu nome e sobrenome em letra minúscula. Ex: Daniel Paulino Alves (dpa).

Dessa forma, o pacote gerado terá o seguinte padrão: GODPageStructure—dpa-1.mcz. O número 1 é a sequência de versões geradas e é colocado automaticamente pelo Monticello.

Quanto a mensagem de commit, sempre coloque comentários ilustrativos (em inglês) relacionados com as alterações que fez no pacote. Não escreva somente “new version”, “new changes” ou “update”. Este tipo de mensagem não comunica nada do que foi feito.

 

Métodos:

Em Smalltalk, os métodos são agrupados por categorias. As categorias servem para indicar funções que os métodos exercem. Alguns exemplos de categorias mais comuns são:

initialization, comparing, converting, accessing, private, testing, event handling etc.

Os nomes dos métodos são no formato camelCase começando com letras minúsculas. O ideal é que o nome dos métodos indiquem claramente a ação que será feita.

Métodos de teste devem começar com o termo test.

 

Variáveis:

As variáveis de classe (equivalentes às classes estáticas) devem seguir o mesmo formato CamelCase, começando com letras maiúsculas. As variáveis de instância da classe e variáveis dos métodos devem ser em camelCase começando com letras minúsculas. Além disso, os nomes dos variáveis devem fazer sentido.

Ex: uma variável de uma classe “Book” pode ter variáveis como “title” e “author”, e jamais “t” e “a”.

 

Comentários:

Uma boa (e desejada) prática é colocar comentários nas classes, com uma breve explicação sobre suas funcionalidades. Isto é especificamente verdadeiro quando a classe em questão é utilizada em pacotes de outros grupos. No Squeak, usa-se o botão "?" abaixo do espaço reservado às classes para adicionar comentários.

Já quanto a métodos, comentários explicando tanto sua assinatura e argumentos quanto trechos de código interno são dispensáveis, em geral. Afinal, muitas vezes, apenas um nome de método bem escolhido já é suficiente para facilitar o entendimento do código. Normalmente, a necessidade de se comentar uma determinada parte do código é sinal de que:

  • Métodos e variáveis envolvidos não possuem nomes suficientemente explicativos e/ou
  • O trecho em questão é complexo demais e deveria ser extraído para outro método, facilitando o entendimento.

Ou seja, comentários em excesso são indicadores de refatoração necessária (também chamado de bad smell).

 

E lembrem-se:

  • Antes de começar a programar carregue a última versão do projeto do repositório na sua imagem para minimizar problemas com conflito de versões.
  • Quando terminar de fazer suas alterações no código, salve as mudanças no repositório para que seu grupo e os demais tenham acesso à versão mais atual. É recomendável salvar o trabalho a cada pequena alteração, desde que devidamente testadas, é claro! Isto aumenta o controle sobre o código e evita eventuais perdas. :D