Differences

This shows you the differences between two versions of the page.

--- prog1:estilo [2024/03/07 21:06] – link conduta beco
+++ prog1:estilo [2024/03/07 21:47] (current) – external edit 127.0.0.1
@@ Line 3: / Line 3: @@
 # Como contribuir
-Sua contribuição ao código é essencial para tornar o este programa cada vez melhor. Além disso, é difícil para apenas um desenvolvedor testar a imensa quantidade de plataformas e a miríade de configurações existentes. Este guia está aqui para tornar mais simples sua contribuição e aumentar as chances dela ser aceita. Há apenas algumas regras que precisamos para que consigamos manter a organização e o controle do código, então basta seguir este pequeno guia de '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
@@ Line 9: / Line 11: @@
 Tenha certeza de que sua conta está devidamente configurada. Cheque os seguintes itens:
-* Cadastre-se no GitHub :)
+* Cadastre-se no servidor Draco
-* Nas configurações do git em sua máquina local confira se seu nome e email são os mesmos que cadastrou no GitHub.
+* Cadastre-se no Dropbox
-* Siga o código de [conduta do bom programador BecoSystems](conduta)
+* Cadastre-se no grupo por email Contauto (google groups, prefira gmail)
-* Faça um _fork_, implemente e teste o programa.
+* Cadastre-se no GitHub
-* Para um _pull request_ ser aceito é **essencial** que as alterações sejam em doses bem pequenas (homeopáticas), mudando apenas um bloco lógico consistente em cada requisição.
+* Baixe para seu computador/notebook os textos do hydrabox (Dropbox)
-* A requisição (_pull request_) deve ser feita preferencialmente de _master_ para _master_, para facilitar a comparação de códigos e padronizar os _forks_
+    - Leia-os atentamente. Lá as explicações são muito mais detalhadas que as que você lerá neste pequeno guia
-* Faça testes à vontade no ramo _develop_ ou outro qualquer. Mas tente manter o ramo _master_ fiel ao _upstream_.
+* 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](conduta)
+# 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 _upstream_
+* 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 _upstream_
+* 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
-* COPYING
+* Arquivo fonte e arquivos de bibliotecas
-* GPL-pt_BR.txt
+* As extensões são, fonte e binário, respectivamente (exemplo para exercício 11):
-* engines.ini
+    - Linguagem C: ex11.c e ex11 ou ex11.x
-* livro.txt
+    - Biblioteca em C: ex11.h
-* wb2uci.eng
+    - Linguagem C++: ex11.cpp e ex11.out
-* winboard.ini
+    - Biblioteca em C++: ex11.hpp
-* xadreco-icon.png
+    - Linguagem Rust: ex11.rs e ex11
-* xadreco-logo1.jpg
+    - Linguagem Zig: ex11.zig e ex11
-* xadreco.c: código fonte em C
+    - PROLOG: ex11.pl (e se houver, ex11.pl.x)
-* xadreco.h: biblioteca
+    - Portugol: ex11.gpt e ex11.gpt.x
-* zippy-frases.txt
+    - 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 (modificado automaticamente pelo _make_)
+* 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.txt
 * README.md: em sintaxe de Markdown, contém a "capa" que aparece no GitHub. Deve ter uma explicação sobre:
     - O que é o programa
@@ Line 43: / Line 117: @@
     - Licença
     - Referências: Links para páginas relevantes
+* Outros arquivos relevantes
 * Índice _ctags_ opcional
 * _.gitignore_ : faz o git ignorar certos arquivos
@@ Line 67: / Line 142: @@
     int p; /* a really though condition */
-    p = !(is_bar[0] || isBar[1]);
+    p = !(is_bar[0] || is_bar[1]);
-    /* check if it's beer number 2 and not in some funny condition */
     if(is_bar[x] == 2 && !p)
     {
@@ Line 79: / Line 153: @@
 }
+```
+### 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!
+...
 ```
@@ Line 89: / Line 212: @@
 ### Comentários
-* Use comentários /* estilo C */
+* Use comentários `/* estilo C */`
-* Coloque um espaço após o /* e um antes do */
+* 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
@@ Line 97: / Line 220: @@
 * 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
+    - `/* 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.
+    - `/* BUG: esta errado assim e assado */` : para indicar um bug conhecido que precisa ser corrigido no futuro.
 ### Comentários DOXYGEN
@@ Line 161: / Line 284: @@
 * 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 1`)
+    - 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
@@ Line 167: / Line 290: @@
 * 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 início de _typedef_. Exemplo: `typedef int t_meuint;`
+* 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: `t_carro *pcarro;` ou `char *pnome;`.
+* 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.
@@ Line 193: / Line 317: @@
 * 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 na sua máquina local?
+    - Tudo configurado no GitHub e no Draco?
-    - Repositório criado no GitHub com _fork_
+    - Repositório criado no GitHub (seu ou com _fork_ conforme o caso)
-    - Faça o _clone_ na sua máquina
+    - Faça o _clone_ no Draco
-    - Crie seu ramo _feature-nome_ ou vá para _develop_
+    - Crie seu ramo _feature-nome_
-    - Siga a partir do passo (1)
+    - 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_ ou _develop_
+    - 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_)
@@ Line 215: / Line 355: @@
         * Faça _merge_ do _feature-nome_ com o _develop_
         * Resolva conflitos se houver
-        * Teste o programa muitas vezes e corrija se necessário
         * Faça o _push_ do _develop_ para o GitHub
-        * Ou, se usou apenas o _develop_, faça o _push_
+    - (7) Dia de _release_ no _master_:
-    - (7) Dia de finalizar o _master_ e pedir um _pull request_
         * Vá para o _master_ e atualize-o
         * Faça _merge_ do _develop_ com o _master_
         * Resolva conflitos se houver
-        * Teste o programa muitas vezes e corrija se necessário
         * Faça o _push_ do _master_ para o GitHub
-        * Tudo pronto, faça o _pull request_ e torça para ser aceito
+        * 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 _push_! O _push_ é irreversível, manda para o GitHub. Enquanto estiver só na sua máquina você pode corrigir quaisquer _bugs_
+* 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 testes
+* 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? Então faça o _push_!
+* Tudo ok? O programa compila sem erros e avisos? Está quase na hora do _commit_ então... Mas falta algo importante: indentação!
-* 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_.
+* 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**.
-* No _pull request_ coloque um título descritivo.
+* 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 a mensagem com apenas um título com o comando `git commit -am "uma descricao do que este commit faz em ate 50 caracteres"`
+* 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. Use os comandos:
+* 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_ (ou seu editor preferido) para você digitar uma mensagem de _commit_ maior.
+    - `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` (no _vi_) para salvar e fazer o _commit_
+        * Saia com `:x` para salvar e fazer o _commit_
-        * Saia com `:q!` (no _vi_) para abortar a edição e **não** 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_:
@@ Line 293: / Line 436: @@
 *.c text
 *.h text
-*.txt text
-*.ini text
-*.eng text
 *.x binary
-*.jpg binary
-*.png binary
 ```
@@ Line 306: / Line 444: @@
 # Obrigado!
-Agora é com você! Divirta-se programando!
+Agora é com você! Bom estudo!
 Atenciosamente,
 Prof. Dr. Ruben Carlo Benante \<<rcb@beco.cc>\>
-Autor do Xadreco
 </markdown>