Diferenças

Aqui você vê as diferenças entre duas revisões dessa página.

--- ti_publica:desenvolvimento_de_sistemas:boas_praticas [2019/04/02 17:42] – created cartola
+++ ti_publica:desenvolvimento_de_sistemas:boas_praticas [2019/11/21 21:07] – [Desenvolvimento de sistemas: boas práticas] cartola
@@ Linha 2: / Linha 2: @@
 Tentei reunir aqui boas práticas que gosto de usar para programar. São dicas pessoais que alguns podem preferir não usar, mas as obtive de várias fontes e muitas são de consenso
-geral. Algumas dicas são genéricas, outras mais adequadas a uma ou outra linguagem. Quando comecei a escrever estava programando principalmente em python, mas também frequentemente em
+geral. Algumas são avaliadas para considerar se o código é bom. Algumas dicas são genéricas, outras mais adequadas a uma ou outra linguagem. Quando comecei a escrever estava programando principalmente em python, mas também frequentemente em
 shell (principalmente bash) e as vezes em php. No passado já programei em C, pascal, perl, fortran e talvez alguma outra linguagem que não estou lembrando agora.
-=====Para escrever bom código=====
+Veja também:
+  * [[:boas_praticas_de_programacao_shell_script|Boas práticas de programação shell]]
+  * [[ti_publica:dicas_python|Dicas para Python]]
-====Geral====
+=====Dicas gerais=====
-  * Use um lint(ou linter) pra checar vários aspectos do código. Ex: [https://www.pylint.org/]
+  * Use um lint(ou linter) pra checar vários aspectos do código. Ex: [[https://www.pylint.org/|Pylint]] (python), [[https://www.shellcheck.net/|shellcheck]] (shell)
-  * Criar testes automatizados
+  * Crie testes automatizados
-  * Não usar linhas maiores que 80 caracteres
+  * Não use linhas maiores que 80 caracteres
-  * Crie e use bibliotecas de funções
+  * Crie e use funções, classes, bibliotecas
+  * Não faça blocos de código longos
+  * Primeira linha de um código interpretado (linha shebang):
+    * Em ambientes Unix like (Linux, BSDs, AIX, Solaris, Mac OS etc)
+      * prefira: #!/usr/bin/env python
+      * do que: #!/usr/bin/python
+      * fica mais flexível, mais chance de funcionar em ambientes distintos
+      * **não serve** caso precise de um interpretador específico que não o padrão do sistema
+  * Se for publicar seu código publique em inglês
+===Documentação===
+Um projeto de software certamente necessita de arquivos somente de documentação com temas como escopo, regras de negócio, cronograma, papéis e responsabilidades da equipe, requisitos, licenças etc. Em projetos menores muitas vezes isso tudo pode estar num único arquivo LEIAME.txt ou, seguindo a tendência do [[https://help.github.com/pt/github/writing-on-github/basic-writing-and-formatting-syntax|github]], README.md, que pode ser escrito com [[https://pt.wikipedia.org/wiki/Markdown|Markdown]] e será apresentado ao acessar um diretório via web num repositório GIT.
+Isso tudo, porém, não exclui uma boa documentação no próprio código, que é do que falo aqui.
+  * Use um cabeçalho em cada arquivo de código:
+    * Descrição do propósito, parâmetros, requisitos, etc
+    * Autor
+    * Histórico
+    * A fazer
+  * Comente os blocos: funções, classes, métodos, loops, variáveis ...
+    * Pylint pede doc para o arquivo, funções e classes, por exemplo
+    * vim-youcompleteme fornece as docs de funções ao digitar seus nomes
+**Exemplo de cabeçalho padrão (python):**
+  #!/usr/bin/env python3
+  # -*- coding: UTF-8 -*-
+  #
+  # <Descrição> A segunda linha acima permite o uso de acentuação no arquivo
+  #
+  #
+  # Historico (mais recente em cima)
+  #       27.11.2018 - <identificação da pessoa> - Criação
+  #       13.12.2018 - <identificação da pessoa> - Lorem Ipsilum
+  #
+  # A Fazer
+  #       - Tarefa 1
+  #       - Tarefa 2
+  #               - subtarefa 2.1
 ===Variáveis===
-  * Dar nomes descritivos a variáveis e funções
+  * Dar nomes descritivos a variáveis e funções, usar sempre mesmos verbos e substantivos
-  * Adotar camelCase ou snake_case para nomear variáveis e funções
+  * Adotar camelCase ou snake_case para nomear variáveis e funções e manter coerência num mesmo código
   * Adotar maiúsculas para constantes
   * Não usar números diretamente, crie uma constante que diga no nome o que ele é (ex: PI, RAIO_DA_TERRA, etc)
@@ Linha 22: / Linha 64: @@
 ===Funções / Objetos===
-  * Descrever todas as funções
+  * Descrever todas as funções nelas mesmas
   * Criar funções pequenas, segmentando o código
   * Eliminar flags booleanos
@@ Linha 33: / Linha 75: @@
   * Evitar efeitos colaterais
   * Evitar variáveis globais!!!! (vale repetir)
+===Formatação===
+Lembre-se que outra pessoa pode mexer no seu código mesmo que você não preveja isso inicialmente. Além disso você mesmo pode não lembrar mais o que você fez.
+  * Indente sempre bem ou pode entender errado que comandos estão dentro de que estruturas. Com uma IDE isso é bem fácil
+  * O uso de um lint(er) pode ajudar a identificar algumas faltas de padrão
+  * Um formatador, [[https://github.com/ambv/black|como o black pra Python]], ajuda a manter o código coerente (formatando coisas opcionais sempre da mesma forma) e legível
 ===Testes automatizados===
+  * Algumas linguagens já tem frameworks prontos para adiantar esse trabalho, como o [[https://docs.pytest.org/en/latest/|pytest para Python]], [[https://github.com/kward/shunit2|shUnit2]] ou [[https://liw.fi/cmdtest/|cmdtest/yarn]] para Shell, [[https://phpunit.de/|PHPUnit]] etc
   * Criar funções ou classes que recebam e retornem parâmetros testáveis
-  * Criar outro programa que teste, com os testes programados ou preparar trecho do programa para atuar nos testes (python pode usar o artifício do __main__)
+  * Criar outro programa que teste, com os testes programados ou preparar trecho do programa para atuar nos testes
+  * Uso de <code python>if __name__ == "__main__":</code> no Python para diferenciar quando o script está sendo chamado diretamente e quando está sendo carregado por outro, visando não executar o programa principal se estiver sendo testado
 ===IDE===
-  * Use checagem de sintaxe no VIM e auto compleção
+Eu uso o vim, mas essas funcionalidades provavelmente poderão ser encontradas em outras IDEs.
-    * vim-syntastic
-    * vim-youcompleteme
+  * Checagem de sintaxe e auto complemento no VIM
+    * [[https://github.com/vim-syntastic/syntastic|vim-syntastic]]
+    * [[https://github.com/ycm-core/YouCompleteMe|vim-youcompleteme]]
+  * Configurações no .vimrc:
+    * set textwidth=80
+    * set wrapmargin=8
+    * set columns=80
 ===Reuso===
   * Ao criar classes/códigos reusáveis, defina a versão (no nível da classe, não da instância)
   * Ao criar número de versão no código use tipo string
-===ETC===
-**Exemplo de cabeçalho padrão (python):**
-  #!/usr/bin/python3
-  # -*- coding: UTF-8 -*-
-  #
-  # <Descrição> A segunda linha acima permite o uso de acentuação no arquivo
-  #
-  #
-  # Historico
-  #       27.11.2018 - <identificação da pessoa> - Criação
-  #       13.12.2018 - <identificação da pessoa> - Lorem Ipsilum
-  #
-  # A Fazer
-  #       - Tarefa 1
-  #       - Tarefa 2
-  #               - subtarefa 2.1
 =====Referências=====
@@ Linha 72: / Linha 108: @@
   * Vídeo [[https://www.youtube.com/watch?v=HTLu2DFOdTg|Python's Class Development Toolkit]] - bom para programar classes reutilizáveis, muitas dicas próprias de python.
   * [[https://en.wikipedia.org/wiki/Zen_of_Python|Zen of Python]]
+  * Cursos gratuitos da USP no Coursera:
+    *  [[https://www.coursera.org/learn/ciencia-computacao-python-conceitos|Introdução à Ciência da Computação com Python Parte 1]]
+    * [[https://www.coursera.org/learn/ciencia-computacao-python-conceitos-2|Introdução à Ciência da Computação com Python Parte 2]]