Desenvolvimento Aberto

Documentação de API e linters
Igor dos Santos Montagner ( igorsm1@insper.edu.br )
Igor Montagner License CC BY-NC-SA 4.0

Discussão: o que faz o projeto?

Igor Montagner License CC BY-NC-SA 4.0

Servidor de desafios

Vocês rodaram um MVP do servidor de desafios. Veja abaixo seu estado atual:

https://github.com/Insper/servidor-de-desafios

Igor Montagner License CC BY-NC-SA 4.0

Servidor de desafios

Igor Montagner License CC BY-NC-SA 4.0

Discussão: como o projeto está organizado? (tecnologias)

Igor Montagner License CC BY-NC-SA 4.0

Discussão: como o projeto está organizado? (código)

Igor Montagner License CC BY-NC-SA 4.0

Discussão: avalie a arquitetura do projeto

0 a 10

Igor Montagner License CC BY-NC-SA 4.0

Discussão: avalie a qualidade de código do projeto.

0 a 10

Igor Montagner License CC BY-NC-SA 4.0

Discussão: avalie a segurança do projeto.

0 a 10

Igor Montagner License CC BY-NC-SA 4.0

Discussão: esse projeto é um projeto "profissional"?

0 a 10

Igor Montagner License CC BY-NC-SA 4.0

Discussão: o que você incluiria na documentação do projeto?

Igor Montagner License CC BY-NC-SA 4.0

Software tem história e depende de pessoas para evoluir

Igor Montagner License CC BY-NC-SA 4.0

Código vs software profissional

Os seguintes pontos transformam um código que fiz para mim em algo útil para outras pessoas

  1. Traduções e internacionalização (datas)
  2. Documentação de usuário e de desenvolvimento
  3. Algum processo de qualidade de software
    • testes automatizados
    • formatação de código e estrutura de repo
  4. pacotes de instalação
Igor Montagner License CC BY-NC-SA 4.0

Hoje

  • Ferramentas de documentação
  • Documentação de API usando
  • Padrões de formatação de código
    • linters
    • PEP8
Igor Montagner License CC BY-NC-SA 4.0

Documentação de API

Objetivo: explicar o funcionamento das funções, classes e módulos de um programa.

  • Focado em detalhes
  • Documenta os argumentos esperados e em quais situações a função funciona
  • Tipicamente obtida direto do código
  • Não detalha como as funções são usadas em conjunto
Igor Montagner License CC BY-NC-SA 4.0

Documentação de API

center

Igor Montagner License CC BY-NC-SA 4.0

Documentação de API

center

ref

Igor Montagner License CC BY-NC-SA 4.0

Ferramentas

  • Python:
    • pydoc, numpydoc
  • C/C++
    • Doxygen
  • Java
    • Javadoc

Em geral podem ser plugadas em alguma ferramenta de documentação de projetos.

Igor Montagner License CC BY-NC-SA 4.0

Padrões de codificação

Igor Montagner License CC BY-NC-SA 4.0

Padrões de codificação

Igor Montagner License CC BY-NC-SA 4.0

Padrões de codificação

  • Cada projeto tem o seu
  • Algumas linguagens tem um estilo padrão
    • Python - PEP8
  • Ferramentas ajudam a conferir (forçar) um estilo específico
Igor Montagner License CC BY-NC-SA 4.0

Ferramentas

  • Python: pylint, black
  • C/C++: splint, cppchecker, gcc (opções -Wall, -Wextra), clang-format/-tidy
  • Java: flag -Xlint
  • Javascript: ESlint, TSlint (typescript)

Ajudam a manter código limpo e legível. Podem ser plugadas no seu editor favorito.

Execução obrigatória para muitos projetos grandes

Igor Montagner License CC BY-NC-SA 4.0

Atividade prática: Projeto profissional

Objetivo: Transformar um código perdido em um projeto

"metadata": {"url": "github pages criado", "group": ["ate três", "alunos"]}

Igor Montagner License CC BY-NC-SA 4.0

Desenvolvimento Aberto

Documentação de API + testes
Igor dos Santos Montagner ( igorsm1@insper.edu.br )
Igor Montagner License CC BY-NC-SA 4.0