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)
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)
-
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)
O estilo de indentação
Linguagem C
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.
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:
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 (*)
-
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
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.
Dicas de configuração
Final de linha estilo Unix ()
# Arquivo .gitattributes
* text=auto
*.c text
*.h text
*.x binary
Obrigado!
Agora é com você! Bom estudo!
Atenciosamente,
Prof. Dr. Ruben Carlo Benante <rcb@beco.cc>