O documento fornece recomendações de boas práticas para codificação em Jupyter Notebooks, incluindo usar um padrão de estilo de código como PEP8, usar nomes descritivos para variáveis e funções, evitar código duplicado, encapsular código em funções e classes, e remover código complexo do notebook sempre que possível.

1. indeorum.com
Boas Práticas de Programação para
Jupyter Notebooks
Joel Pinho Lucas
26/08/2020

2. ROTEIRO
1 Por que se preocupar com boas práticas ao
codificar notebooks?
2 Diferenças de notebooks para programação
tradicional
3 Compilado de recomendações de boas
práticas
indeorum.com
4 Fontes para consulta

3. indeorum.com
De onde vêm os cientistas de dados?

4. indeorum.com
“Sou Cientista de Dados… não preciso me preocupar com
legibilidade de código porque a maior parte dele vai fora.”
http://thedataist.com/ten-good-coding-practices-for-data-scientists/
“Código limpo e agilidade valem para desenvolvedores…
não fazem sentido dentro do meu trabalho.”

5. indeorum.com
E SE…
• outras pessoas usarem meu notebook?
• eu (ou outra pessoa) precisar alterá-lo?
• precisar aproveitá-lo para outros entregáveis?
• precisar colocar um modelo em produção?
• precisar escalar o modelo?
• precisar depurar?
• dados de input mudarem / modelo depreciar?

6. Notebooks são
Software!!
indeorum.com

7. indeorum.com
ESPECIFICIDADES DE JUPYTER
NOTEBOOKS
• Ambiente livre e flexível, permite iterar e explorar datasets rapidamente
• Também são usados para gerar relatórios
• Em projetos de ML a maior parte do código contém transformações de
dados, demandando input e output com o mesmo padrão
• Precisam gerar artefatos reproduzíveis

8. indeorum.com
ESPECIFICIDADES DE JUPYTER
NOTEBOOKS
• Permitem executar código fora de ordem, preservando o contexto
• São excelentes para experimentação e prototipação, mas não para código
em produção

9. indeorum.com
ESPECIFICIDADES DE JUPYTER
NOTEBOOKS
• Versionamento complexo…

10. indeorum.com
Experimentação
X
Produção
https://cloud.google.com/blog/products/ai-machine-learning/best-practices-that-can-improve-the-life-of-any-developer-using-jupyter-notebooks

11. indeorum.com
Recomendações de Boas Práticas

12. Usar um padrão
de estilo de
código
1.
indeorum.com

13. indeorum.com
PEP8 - https://www.python.org/dev/peps/pep-0008
• Linhas com no máximo de 79 caracteres
• Linha em branco separando blocos lógicos dentro de métodos e funções
• Não usar espaço imediatamente antes ou após um parêntese
• Importações em linhas separadas
• etc…

14. Meaningful
Names
2.
indeorum.com

15. indeorum.com
Ruim
Bom
Usar nomes descritivos!

16. indeorum.com
Evitar notação húngara
(tipo no nome)!
Ruim
Bom
Bom
Ruim

17. indeorum.com
Funções e métodos devem
ser verbos!
Ruim
Bom

18. DRY
3.
indeorum.com

19. indeorum.com
Ruim
https://github.com/davified/clean-code-ml/blob/master/docs/functions.md

20. indeorum.com
Bom
https://github.com/davified/clean-code-ml/blob/master/docs/functions.md

21. Cuidado com
Dead Code
4.
indeorum.com

22. indeorum.com
Ruim
Bom

23. Encapsular e
encapsular
5.
indeorum.com

24. indeorum.com
Ruim
Exercitar Princípio da
Responsabilidade Única!

25. indeorum.com
Bom

26. indeorum.com
Abstrair detalhes da lógica de negócio que
estejam vinculadas a uma entidade específica:
Bom
Ruim

27. indeorum.com
https://towardsdatascience.com/clean-machine-learning-code-bd32bd0e9212

28. Moderação e
atenção no uso de
comentários
6.
indeorum.com

29. indeorum.com
O código sempre deve dizer a verdade!
Bom
Ruim

30. indeorum.com
• Comentários podem ser indício de má abstração, bad naming, exceção de
responsabilidades em funções/classes, etc.
• Priorizar células de markdown para descrever especificadas relacionadas
ao negócio ou a um modelo
• DocStrings são recomendados

31. Preferir bibliotecas
pré-existentes
7.
indeorum.com

32. indeorum.com
Ruim
Bom

33. indeorum.com
Ruim
Bom

34. Tirar Código do
Notebook sempre
que possível
8.
indeorum.com

35. indeorum.com
• Jupyter Notebooks se enquadram no ‘princípio da superfície plana’.
• Quanto maior o notebook, mais difícil será para verificar o resultado de
eventuais alterações
• Retirar complexidade de classes e funções auxiliares e dar foco para
análise exploratória e para predições com ML

36. indeorum.com
Exemplos de tipo de código que devem sair de notebooks:

37. Implementar
Testes Unitários
9.
indeorum.com

38. Bom

39. indeorum.com
FONTES
• Clean Code - Robert C. Martin, Michael C. Feathers (Autor), Timothy R. Ottinger.
2008
• Thoughtful Machine Learning with Python: A Test-Driven Approach - Matthew
Kirk. 2017
• Guia de Estilo para Python: https://www.python.org/dev/peps/pep-0008/
• https://medium.com/zero-equals-false/writing-clean-code-for-data-scientists-
f141bf550d37
• https://www.thoughtworks.com/insights/blog/coding-habits-data-scientists
• Clean code em Python: https://github.com/zedr/clean-code-python

40. indeorum.com
FONTES
• Clean code em ML: https://github.com/davified/clean-code-ml
• https://towardsdatascience.com/clean-code-for-a-data-scientist-f4b760374b74
• https://towardsdatascience.com/clean-machine-learning-code-bd32bd0e9212
• http://thedataist.com/ten-good-coding-practices-for-data-scientists/
• https://www.kaggle.com/baghern/a-deep-dive-into-sklearn-pipelines
• https://towardsdatascience.com/pre-process-data-with-pipeline-to-prevent-
data-leakage-during-cross-validation-e3442cca7fdc

41. Explorar
Extensões do
Jupyter
12.
indeorum.com

42. indeorum.com
1. toc2 (numeração automática de markdown):
https://jupyter-contrib-nbextensions.readthedocs.io/en/latest/nbextensions/toc2/
2. Debug de variáveis:
https://jupyter-contrib-nbextensions.readthedocs.io/en/latest/nbextensions/varInspector/
3. Minimização de células:
https://jupyter-contrib-nbextensions.readthedocs.io/en/latest/nbextensions/collapsible_headings/

43. OBRIGADO!
joelpl@gmail.com
indeorum.com