Como contribuir

Sua contribuição ao código é essencial pois é através dela que você demonstra o seu conhecimento, seu entendimento das características (das básicas até as mais sutís) do programa, e também a sua atividade e determinação.

Para que suas contribuições sejam maximizadas (o que impacta positivamente sua nota), siga este pequeno guia de 'Como contribuir'.

Iniciando

Tenha certeza de que sua conta está devidamente configurada. Cheque os seguintes itens:

• Cadastre-se no servidor Draco
• Cadastre-se no Dropbox
• Cadastre-se no grupo por email Contauto (google groups, prefira gmail)
• Cadastre-se no GitHub
• Baixe para seu computador/notebook os textos do hydrabox (Dropbox)

  • Leia-os atentamente. Lá as explicações são muito mais detalhadas que as que você lerá neste pequeno guia
• No Draco, crie uma chave SSH
• Adicione sua chave SSH pública para login no Github
• Nas configurações do git no Draco, confira seu nome completo e email (o mesmo que usou para se cadastrar no GitHub)
• Nas configurações do GitHub:

  • coloque seu nome completo no perfil
  • habilite mostrar suas contribuições privadas nas estatísticas
  • aceite o convite para o time do BecoSystems da disciplina/semestre que está cursando
  • acesse o link do GitHub classroom para iniciar uma atividade (pegue o link com o professor)
• Siga o código de Código de Conduta BecoSystems

Repositório

Os trabalhos podem ser em grupos ou individuais, com ou sem repositório upstream. Confirme em aula como será cada exercício.

Trabalhos pelo Classroom (assignments)

• O professor enviará um email com o link para o cadastro do grupo e o repositório será criado automaticamente para cada grupo.
• Não tem upstream.
• Todos devem fazer o clone do repositório no Draco.
• Ao final, faça também um clone (ou copie a pasta clonada em rascunhos) na pasta trabalhos no Draco.

Trabalhos em grupos criados manualmente (BecoSystems)

• Os alunos se dividem em grupos e um representante cria o repositório e adiciona todos os outros como colaboradores.
• Não tem upstream.
• Todos devem fazer o clone do repositório no Draco.
• Ao final, faça também um clone (ou copie a pasta clonada em rascunhos) na pasta trabalhos no Draco.

Trabalhos em grupo com

• O professor cria o repositório upstream e adiciona os colaboradores com permissão de apenas leitura.
• Um representante de cada time fará um fork
• Este representante adiciona todos os outros membros do time como colaboradores deste fork. Ninguém mais faz fork.
• O representante também configura o seu fork para permitir a criação de issues.
• Os issues no upstream são usados para comunicar com todos os times e tratar de problemas que envolvem todos globalmente (como API por exemplo).
• Os issues no origin (repositório do fork feito por cada time) são usados para comunicação interna do time, para tratar problemas locais.
• O código vai sendo colaborativamente adicionado no upstream pelo professor, conforme cada aluno faz um pull request
• Todos devem fazer o clone do repositório no Draco.
• Ao final, faça também um clone (ou copie a pasta clonada em rascunhos) na pasta trabalhos no Draco.

Trabalhos individuais com

• O professor cria o repositório upstream e adiciona os colaboradores com permissão de apenas leitura.
• Cada aluno faz seu fork e trabalha de forma individual.
• O código vai sendo colaborativamente adicionado no upstream pelo professor, conforme cada aluno faz um pull request
• Todos devem fazer o clone do repositório no Draco.
• Ao final, faça também um clone (ou copie a pasta clonada em rascunhos) na pasta trabalhos no Draco.

Antes de mais nada!

• Confira se você está trabalhando no ramo feature-nome ou develop
• NUNCA (never, jamais, mai, noot, nie, em tempo algum) o master ficará na frente do develop

Editor de textos

O editor de textos usados é o vi (lê-se "vi-ai") ou vim (que é o vi improved), disponível na quase totalidade dos sistemas Linux, Unix e Mac (existe também para instalação gratuita em Windows). Sua grande vantagem é a operação remota, além de uma quantidade enorme de comandos para configuração e facilidades para programação.

O vi é um excelente editor para quem o conhece. Para quem não o conhece, é difícil e pode ser muito frustrante.

Felizmente existe um excelente arquivo em PDF na pasta hydrabox com explicações sobre a maioria dos comandos. Não deixe de ler.

Atividade registrada

Tenha certeza de seguir estas recomendações para ter um maior aproveitamento:

• Se possível, faça login todo dia no Draco
• Os comandos lá digitados são registrados e contam para sua atividade
• Leia o arquivo sobre Linux no hydrabox
• Configure sua conta, ajuste seu arquivo .project com seus hobbies, faça bom uso de toda a ferramenta, explore, aprenda.
• Confira suas estatísticas no GitHub: seu perfil pessoal e as estatísticas de cada repositório que estiver trabalhando. Tenha certeza que seus commits estão sendo registrados em seu nome e que aparece nos gráficos.
• Desafio: Mantenha a grade do seu perfil com quadradinhos verdinhos durante todo o semestre! E não pare mais: incorpore o GitHub em todos seus projetos de faculdade e leve-o para sua vida. É a rede social do programador, muito mais útil que o Facebook! ;)

Arquivos no repositório

• Arquivo fonte e arquivos de bibliotecas
• As extensões são, fonte e binário, respectivamente (exemplo para exercício 11):

  • Linguagem C: ex11.c e ex11 ou ex11.x
  • Biblioteca em C: ex11.h
  • Linguagem C++: ex11.cpp e ex11.out
  • Biblioteca em C++: ex11.hpp
  • Linguagem Rust: ex11.rs e ex11
  • Linguagem Zig: ex11.zig e ex11
  • PROLOG: ex11.pl (e se houver, ex11.pl.x)
  • Portugol: ex11.gpt e ex11.gpt.x
  • Texto Markdown: ex11.md
  • Texto Wiki: ex11.wiki
  • Bash Script: ex11.sh
  • Assembly: ex11.s (sintaxe AT&T)
• AUTHORS: lista os autores do programa (em grupo ou individual)
• LICENSE: a licença do programa (prefira GNU GPL v2, MIT ou BSD-3)
• VERSION: contém o número da versão atual (de preferência modificado automaticamente pelo make)
• makefile: o script rodado pelo comando make
• README.md: em sintaxe de Markdown, contém a "capa" que aparece no GitHub. Deve ter uma explicação sobre:

  • O que é o programa
  • Como compilar
  • Quais opções para iniciar a execução
  • Como funciona, quais opções durante execução
  • Lista de autores
  • Licença
  • Referências: Links para páginas relevantes
• Outros arquivos relevantes
• Índice ctags opcional
• .gitignore : faz o git ignorar certos arquivos
• .gitattributes : permite configurar atributos por arquivo (veja abaixo)

Formatação

O estilo de indentação

Linguagem C

• A indentação é feita de acordo com o estilo A1 descrito pelo astyle, também conhecido por --style=allman, --style=bsd ou --style=break.

O estilo Allman é um entre mais de 15 estilos e variantes disponíveis e encontradas em vários tipos de código. Não misture os estilos. Este estilo utiliza a seguinte sintaxe, chamada de broken brackets (ou chaves quebradas). Atente para os espaços entre operadores e mudanças de linhas no exemplo abaixo:

/**
 * @ingroup GrupoUnico
 * @brief Breve descricao blablabla
 * ...
 */
int foonc(int is_bar[MAX], int x)
{
    int p; /* a really though condition */
    
    p = !(is_bar[0] || is_bar[1]);

    if(is_bar[x] == 2 && !p)
    {
        bar(p + 1);
        return 1;
    }
    else
        return 0;
}

PROLOG

• Use 4 espaços para indentar (não use TAB's)
• Não use ; para OR. Prefira repetir a regra (ou fato, claro).
• Deixe um espaço entre a cabeça da regra e o se (:-)

Um exemplo de trecho de código seria:

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Aqui vai a licenca, copyright, etc.
% Uma breve descrição do programa
% Autor, data, email para contato

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Sessao de modulos 

:- dynamic([mulher/1]).

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Sessao da base de conhecimento estatico

% Lista de homens, vivos e mortos
homem(socrates).
homem(platao).

% Lista de homens ainda vivos
vivo(platao).

% Lista de objetos inanimados
pedra(diamante).
pedra(rubi).

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Sessao de regras sobre a mortalidade

% indica as condicoes necessarias para um objeto ser mortal
% caso homem
mortal(X) :-
    vivo(X),
    homem(X).

% caso mulher (clausula dinamica)
mortal(X) :-
    vivo(X),
    mulher(X). % BUG: lembrar de fazer assert!
...

Conheça todos os estilos na página de documentação do astyle.

• Para aplicar o estilo no seu código, pode-se rodar o programa $astyle -A1 ex11.c

Dicas para um bom código fonte:

Comentários

• Use comentários /* estilo C */
• Coloque um espaço após o /* e um antes do */
• Faça comentários em linha nas declarações de variável. int i; /* indice geral */
• Evite comentários em linha em outros locais
• Na medida do possível e do seu conhecimento, escreva tudo em inglês, desde nomes de variáveis até comentários. Se for importante usar português, então escreva as variáveis em inglês e os comentários nas duas línguas. Caso não seja possível, tudo bem usar apenas português.
• Coloque os comentários na linha anterior ao bloco ou comando a comentar
• Não use acentos (nem c-cedilhas) no código ou comentários
• Use as palavras nos comentários:

  • /* TODO: alguma tarefa */ : para indicar algo que falta fazer
  • /* BUG: esta errado assim e assado */ : para indicar um bug conhecido que precisa ser corrigido no futuro.

Comentários DOXYGEN

Antes de cada função, coloque comentários na sintaxe DOXYGEN. O mínimo necessário para bem explicar uma função é detalhar:

• Grupo do módulo: @ingroup
• Resumo: @brief
• Detalhes: @details
• Opcional, pré-condições: @pre
• Parâmetros de entrada: @param[in]
• Parâmetros de saída: @param[out]
• Parâmetros de entrada e saída: @param[in, out]
• Valor de retorno: @return ou @retval (ou ambos)
• Opcional, um aviso: @warning
• Opcional, se a função está depreciada: @deprecated
• Opcional, indicar funções semelhantes: @see
• Opcional, indicar bugs: @bug
• Opcional, indicar to do: @todo
• Opcional, escrever uma nota: @note
• Autor: @author
• Opcional, colocar versão: @version
• Data que foi escrita/modificada: @date (formato YYYY-MM-DD, ano, mes, dia)
• Opcional, caso diferente do resto do código, colocar a licença de copyright: @copyright

O exemplo abaixo mostra somente os campos obrigatórios, e descreve hipotéticas variáveis i, o e z:

/**
 * @ingroup Modulo
 * @brief Breve descricao
 * @details Descricao detalhada
 * que pode estar em multiplas linhas
 *
 * @param[in] i indice de entrada
 * @param[out] o indice recalculado de saida 
 * @param[in,out] z Entra com um valor blablabla e devolve blebleble
 *
 * @return Descricao do que a funcao retorna
 * @author Ruben Carlo Benante
 * @date 2016-06-05
 */

No meio do código

• Apague espaços sobrando ao final da linha
• Não inclua espaços após (, [, { ou antes de }, ] e )
• Use espaços após vírgulas e ponto-e-vírgulas
• Use espaços em volta de operadores (exceto os unários como !)
• Não cometa erros de grafia (não use acentos!)
• Não alinhe tokens verticalmente em linhas consecutivas
• Use indentação de 4 espaços (não use TABS)
• Se quebrar uma linha, indente-a 4 espaços
• Use uma linha em branco entre métodos, funções ou blocos lógicos importantes
• Use final de linha de um byte (\n) estilo Unix (*)
• Deixe uma linha em branco ao final do arquivo conforme padrão POSIX

Variáveis

• Variáveis com letras maiúsculas somente se:

  • São PROLOG, claro ;)
  • São MACROS (logo não são variáveis) em C (exemplo: #define CINCO 5)
  • São MUIIIITO importantes e precisam de algum destaque. Não tente usar assim, pois você provavelmente não vai convencer ninguém. ;)
• Use nomes claros para as variáveis
• O nome da variável deve indicar sua intenção, i.é., o dado que ela carrega.
• Prefira nomes que demonstrem o conceito geral do domínio, ao invés dos padrões que eles implementam.
• Não faça nomes gigantes. Um tamanho máximo que já não fica tão bom é até 15 caracteres. Tente nomes menores, até 10 no pior caso.
• Use o estilo snake, ou seja, as variáveis, caso precisem de nome composto, são criadas todas em minúsculas e com um sublinhado separando-os. Exemplo taxa_anual. Não use o estilo camelo (ex. taxaAnual) e muito menos misture estilos.
• Use sublinhados para sufixos apenas se for criar variáveis que tenham alguma característica em comum. Exemplo: salario_antes e salario_depois. Se existirem muitas características em comum em um tipo de dados, considere agrupar com struct
• Não coloque o tipo no nome da variável. Exemplo: vetor_de_alunos.
• Coloque _t no fim de typedef. Exemplo: typedef int meuint_t;
• Coloque st_ no início de structs. Exemplo: struct st_concreto { ... };
• Coloque s no início de variáveis string. Exemplo: char snome[MAX];
• Coloque p no início de ponteiros. Exemplo: carro_t *pcarro; ou char *pnome;.
• Nomeie uma enum (enumeração) pelo substantivo comum do objeto que ela enumera.

Organização

A ordem que o esqueleto do programa deve ter é como segue:

Em linguagem C

• Comentário com copyright, descrição do programa, autor, contato e data
• Comentários com uma introdução à leitura do código, explicações gerais, compilação, etc.
• O(s) #include <...>
• O(s) #include "..."
• Se o programa não tem uma biblioteca própria, seguem:

  • Os defines
  • Os TAD's (tipos abstratos de dados): struct, enum, typedef, etc.
  • Os tipos globais
  • Os protótipos das funções
• Se o programa tem biblioteca própria, estes ficam no .h
• A função int main(void) ou int main(int argc, char *argv[])
• As outras funções, de preferência em uma ordem que faça um mínimo de sentido com o próprio fluxo do programa

Em PROLOG

• Comentários iniciam como em C (copyright, e explicações gerais)
• Os módulos lidos
• As diretrizes (dynamic, etc.)
• Os fatos
• As regras, em uma ordem que ajude a clarificar a sequência lógica da solução engedrada

Ciclo de trabalho

• Ligou o computador, primeira vez neste repositório

  • Tudo configurado no GitHub e no Draco?
  • Repositório criado no GitHub (seu ou com fork conforme o caso)
  • Faça o clone no Draco
  • Crie seu ramo feature-nome
  • Crie o esqueleto do codigo (exemplo ex11.c)
  • Adicione (git add) o fonte criado
  • Faça o primeiro commit do ramo feature-nome
  • Vá para o develop
  • Faça o merge com o feature-nome
  • Faça o primeiro push do develop
  • Coloque a tag v0.0 e novo push das tags.
  • Faça o merge com o master
  • E faça o primeiro commit e push no master.
• Ligou o computador para trabalhar do segundo dia em diante

  • Atualize todos os ramos remotos (master e develop)
  • Resolva conflitos se houver
  • Vá para seu ramo de trabalho feature-nome (opcional, fazer o merge antes, ou continuar trabalhando e fazer o merge só no final)
  • (1) Edite o arquivo fonte no vi
  • (2) Compile (gcc ou make, ou teste no swipl)
  • (3) Erros: volte para passo (1)
  • (4) Compilou sem erros: faça commit
  • (5) Vai trabalhar mais, volte para o passo (1)
  • (6) Fim do dia de trabalho:

    • Vá para o develop e atualize-o
    • Faça merge do feature-nome com o develop
    • Resolva conflitos se houver
    • Faça o push do develop para o GitHub
  • (7) Dia de release no master:

    • Vá para o master e atualize-o
    • Faça merge do develop com o master
    • Resolva conflitos se houver
    • Faça o push do master para o GitHub
    • Crie uma tag e faça o push das tags
    • Se houve alterações por conflito, o master está na frente do develop, então passe o merge para baixo, para o develop e para o feature-nome:

      • Vá para o develop, atualize-o e merge com master
      • Vá para o feature-nome, e merge com o develop

Teste

• Não tenha pressa de fazer commit e push! Em especial, o push é irreversível, manda para o GitHub. Enquanto estiver só na sua máquina você pode corrigir quaisquer bugs
• Compile. Use todas as chaves de aviso que o gcc pode oferecer. O gcc é seu amigo!
• Crie páginas com mensagens de erro com o comando sprunge para discutir nos issues se necessário
• Use makefile para compilar seus exercícios

  • Não deixe de conhecer as opções do gcc para compilação. Este é um comando fundamental em vários sistemas operacionais, inclusive embarcados (arduino, pic, raspberry pi, etc.)
• Teste! Rode o programa, faça entrada de dados, veja se o que acabou de programar realmente faz o que você deseja, e se não quebrou nada em outra função do programa.
• Tudo ok? O programa compila sem erros e avisos? Está quase na hora do commit então... Mas falta algo importante: indentação!
• Use um formatador automático (veja o astyle). Verifique o código. Agora sim, além de compilar sem erros, também está um CÓDIGO LIMPO.
• Então faça o commit.
• Você pode editar mais, fazer mais commits. No final do trabalho, ou quando achar que é hora, faça o push!
• Se o trabalho exige pull request, faça suas modificações chegarem até o master e então faça o pull request do seu master (origin) para o master do upstream.
• No pull request coloque um título descritivo. Se seu trabalho é em grupo, coloque também no início do título o número do grupo.

Faça uma boa mensagem de commit

• Se é um pequeno commit tudo bem abreviar com o comando git cm "uma descricao do que este commit faz em ate 50 caracteres"
• Mas se é um commit que vai influenciar muito o código de outros ramos ou que vai ser usado para pull request então é importante escrever uma boa mensagem. Neste caso, não use o comando abreviado git cm "mensagem". Use os comandos:

  • git add arquivo : se necessário adicionar algum arquivo
  • git commit : sem abreviação e sem mensagem. Este comando vai abrir o vi para você digitar uma mensagem de commit maior.

    • Na primeira linha, escreva um título do commit com até 50 caracteres, como você já está acostumado.
    • Pule uma linha.
    • Da terceira linha para baixo, descreva com mais detalhes tudo o que você fez, o que este commit inclui, o que muda, qual funcionalidade é acrescentada ou bug é resolvido.
    • Saia com :x para salvar e fazer o commit
    • Saia com :q! para abortar a edição e não fazer o commit
    • Linhas iniciadas com # são ignoradas pelo git como sendo comentários e não são escritas no commit.
• Exemplo de uma boa mensagem de commit:

Faz um exemplo para demonstrar a clareza do commit

Sem este commit a explicação sobre mensagens de commit ficaria falha, sem um exemplo concreto. 
Este é um problema, porque assim fica apenas na imaginação o que seria um bom commit. 
Este commit corrige este problema ao fazer aqui um exemplo concreto e imperativo.

A primeira linha é um título imperativo descritivo do essencial. Os dois parágrafos seguintes, 
o de cima e este, são explicações mais aprofundadas. É importante descrever (1) _o que ocorria_ 
antes do commit, (2) _qual_ é o problema que este commit resolve, (3) _porque_ este comportamento 
é problemático, e (3) _como_ este commit corrige este problema.

Também é possível usar enumerações para clarificar algumas mudanças em pontos 
específicos, como:

* mudafunc() : agora não retorna mais void e sim o código do cliente
* funcoutra() : criada para cumprir outra finalidade que estava faltando
* divideaqui() : criada para cumprir uma finalidade tal e tal que antes 
estava sendo feita na função mudafunc() de modo a ficar mais clara a divisão do que cada função faz.

Lembre que a primeira linha é importante para ver o log e acompanhar a evolução do programa.

• Referência: A Note About Git Commit Messages

Dicas de configuração

Final de linha estilo Unix ()

• Para o final de linha \n, use em suas configurações

  • Linux, Mac ou Unix: git configure --global core.autocrlf input
  • Windows: git configure --global core.autocrlf true
• Outra opção para configurar \n é por repositório. Inclua um novo arquivo .gitattributes com os comandos:

# Arquivo .gitattributes

* text=auto
*.c text
*.h text
*.x binary

• Veja detalhes de como atualizar o repositório após alterar estas configurações na página de help do GitHub
• Veja também configurando o Git

Obrigado!

Agora é com você! Bom estudo!

Atenciosamente,

Prof. Dr. Ruben Carlo Benante <rcb@beco.cc>