Folha de Estilo

---

Histórico de Revisões

Data	Versão	Descrição	Autor
07/09/2017	1.0	Inserção da Folha de estilo	João Paulo
29/10/2017	1.1	Adição da folha de estilo dos testes	Felipe Borges
04/11/2017	1.2	Adição do estilo de nomeação dos testes e class de testes.	Felipe Borges

---

1. Nomeação
2. Formatação
3. Comentários
4. Teste
5. Imports
6. Estilo do Template
7. Estilo da View
8. Estilo da Model
9. Uso do django.conf.settings
10. Estruturas de Decisão
11. Diversos

---

1. Nomeação

• 1.1. Os atributos devem ser nomeados em caixa baixa, com cada palavra separada com um underscore .

      Exemplo : exemplo_de_variavel
  

• 1.2. Os atributos devem ter nomes significativos e auto explicativos.

• 1.3. Os métodos e parâmetros devem ser nomeados em caixa baixa, com cada palavra separada com um underscore.

      Exemplo : exemplo_de_metodo()
  

• 1.4. O nome do método deve representar claramente o que ele faz.

• 1.5. As classes e interfaces devem ser nomeados com a primeira letra em caixa alta.

• 1.6. Os acrônimos devem ser tratados como palavras.

2. Formatação

• 2.1. O código deve ser identado com espaços, utilizando 4 espaços para cada nível de identação.

• 2.2. Os grupos lógicos devem ser separados por uma linha sem nenhum conteúdo.

3. Comentários

• 3.1. Os comentários sempre devem possuir o ponto final, ".", no fechamento do comentário.

• 3.2. Os comentários devem estar no mesmo idioma que está sendo utilizada como padrão de desenvolvimento.

• 3.3. O início do comentário deve ser feito com uma letra Maiúscula.

• 3.4. Deve ser usado # para comentários de uma linha e para comentários com mais de uma linha o comentário deve estar entre as aspas que indicam o início e o fim do comentário.

• 3.4.1 Exemplo 1 :

def function():
    """
    A test docstring looks like this.
    """                  

• 3.4.2 Exemplo 2 :

def function():
#Do something.

• 3.5. Nos testes, o comentário deve indicar o comportamento esperado do teste de forma concisa.

• 3.6. Use TODO comentários para código que é temporário, uma solução de curto prazo ou bom o suficiente, mas não perfeito.

• 3.7. TODO's deve incluir a sequência TODO em caixa alta, seguido pelo nome da pessoa que melhor pode fornecer contexto sobre o problema referenciado pelo TODO, entre parênteses.Exemplo:

# TODO(João) Mudar esse formato de cálculo.

4. Testes

• 4.1. Nos testes deve se usar assertRaisesMessage() em vez de assertRaises() para que a mensagem de exceção possa ser checada.

• 4.2. O nome dos arquivos de teste deve seguir o padrão test_<módulo do MTV>_.py

  test_view_autocomplete.py

ou

  test_model_patient.py

• 4.3. A nomeação da classe de teste deve seguir o padrão:

  Test<Nome da classe a ser testada>

Exemplo:

  class TestAutocomplete:

  class TestUser:

• 4.4. Nomeação do Teste

A nomeação do teste deve seguir o padrão:

  def test_<nome da classe>_<motivo da realização do teste>:

Exemplo :

  def test_autocomplete_search_messages:

5. Imports

• 5.1. Os imports devem estar separados nos seguintes grupos:

  • Future ( futuro )
  • Standard library ( biblioteca padrão)
  • Third-Party libraries ( bibliotecas de terceiros)
  • Django ( outros componentes do Django )
  • Local Django ( componentes locais do Django )
  • Try / excepts

• 5.2. Classifique as linhas de cada grupo em ordem alfabética pelo nome completo do módulo.

• 5.3. Coloque todas as instruções de módulo de importação antes de objetos de importação de módulo em cada seção.

• 5.4. Utilize importações absolutas para outros componentes do Django e importações relativas para componentes locais.

• 5.5. Em cada linha, elenque os itens agrupados com letras maiúsculas antes dos itens em letras minúsculas.

• 5.6. Linhas longas devem ser quebradas usando parênteses e linhas de continuação separadas por 4 espaços. Inclua uma vírgula à direita após a última importação e coloque o parêntese de fechamento em sua própria linha.

• 5.7. Use uma única linha em branco entre a última importação e qualquer código de nível de módulo e use duas linhas em branco acima da primeira função ou classe.Exemplo:

# future
from __future__ import unicode_literals

# standard library
import json
from itertools import chain

# third-party
import bcrypt

 Django
from django.http import Http404
from django.http.response import (
    Http404, HttpResponse, HttpResponseNotAllowed, StreamingHttpResponse,
    cookie,
)

# local Django
from .models import LogEntry

# try/except
try:
    import yaml
except ImportError:
    yaml = None

CONSTANT = 'foo'


class Example(object):
    # ...

• 5.9. Utilize importações de conveniência sempre que disponível. Por exemplo, faça :

from django.views import View

Em vez de :

from django.views.generic.base import View

6. Estilo do template

• 6.1. Coloque um (e apenas um) espaço entre os colchetes e a informação presente.Faça isso:

{{ information }}

Em vez de :

{{information}}

7. Estilo da View

• 7.1. O primeiro parâmetro em uma função de exibição deve ser chamado de request.Faça isso:

def my_view(request, foo):
    # ...

Em vez de :

def my_view(req, foo):
    # ...

8. Estilo da Model

• 8.1. Os nomes dos campos devem ser minúsculos, usando underscores em vez de camelCase.Exemplo:

Faça isso:

class Person(models.Model):
    first_name = models.CharField(max_length=20)
    last_name = models.CharField(max_length=40)

Em vez de:

class Person(models.Model):
    First_name = models.CharField(max_length=20)
    Last_name = models.CharField(max_length=40)

• 8.2. A classe Meta deve aparecer após a definição dos campos, com uma única linha em branco separando os campos e a definição de classe.Exemplo:

Faça isso:

class Person(models.Model):
    first_name = models.CharField(max_length=20)
    last_name = models.CharField(max_length=40)

    class Meta:
        verbose_name_plural = 'people'

Em vez de:

class Person(models.Model):
    first_name = models.CharField(max_length=20)
    last_name = models.CharField(max_length=40)
    class Meta:
        verbose_name_plural = 'people'

Não faça isso também:

class Person(models.Model):
    class Meta:
        verbose_name_plural = 'people'

    first_name = models.CharField(max_length=20)
    last_name = models.CharField(max_length=40)

• 8.3. A ordem de model inner classes e s_tandard methods_ deve ser a seguinte (observando que estes não são todos necessários):

  • Todos os campos de banco de dados
  • Atributos de gerenciador personalizados
  • Classe Meta
  • def str()
  • def save()
  • def get_absolute_url()
  • Quaisquer métodos personalizados

• 8.4. Se as escolhas forem definidas para um determinado campo de modelo, defina cada escolha como uma tupla de tuplas, com um nome totalmente em maiúscula como um atributo de classe na model.Exemplo:

class MyModel(models.Model):
    DIRECTION_UP = 'U'
    DIRECTION_DOWN = 'D'
    DIRECTION_CHOICES = (
        (DIRECTION_UP, 'Up'),
        (DIRECTION_DOWN, 'Down'),
    )

9. Uso do django.conf.settings

• 9.1. Os módulos não devem, em geral, usar configurações armazenadas no django.conf.settings no nível superior (ou seja, avaliado quando o módulo é importado).

10. Estruturas de Decisão

• 10.1. Use sempre o "implícito" falso, se possível.

• 10.2. Nunca use == ou != para comparar singletons como None.Use is ou is not.

• 10.3. Nunca compare uma variável booleana com false usando ==. Use if not x em vez disso.

• 10.4. Para sequências (sequências de caracteres, listas, tuplas), use o fato de que sequências vazias são falsas, então use if not seq: ou if seq: em vez de if len(seq): ou if not len(seq):.

• 10.5. Ao manipular inteiros, o implícito falso pode envolver mais risco do que benefício (ou seja, manipulação acidental do None como 0). Compare um valor que é conhecido por ser um inteiro (e não é o resultado de len ()) contra o inteiro 0.

• 10.6. Exemplos:

  • Correto:

     if not users:
         print 'no users'

     if foo == 0:
         self.handle_zero()

     if i % 10 == 0:
         self.handle_multiple_of_ten()

• Incorreto:

     if len(users) == 0:
         print 'no users'

     if foo is not None and not foo:
         self.handle_zero()

     if not i % 10:
         self.handle_multiple_of_ten()

11. DIVERSOS

• 11.1. Todas strings devem ser marcadas para poderem ser traduzidas.

• 11.2. Instruções de importação que não são mais usadas devem ser removidas quando o código for alterado.

• 11.3 Se uma importação não utilizada precisa permanecer para compatibilidade com versões anteriores, marque o final dela com # NOQA.

• 11.4. Todos os espaços em branco à direita do código devem ser removidos.

• 11.5. O comprimento máximo da linha é de 120 caracteres.As exceções são:

  • Declarações de importação longas.
  • URL's nos comentários.

11. REFERÊNCIAS

• [1]: Django Project Style Guide
• [2]: Google Python Style Guide