Sobre a estrutura básica de um programa em C ou em Python

Antes de apresentar a estrutura dos programas, segue a primeira dica para um "bom código": utilizar "indentação" e comentários adequados.

1. Comentários em meio ao código e o uso adequado de "indentação".

Toda linguagem de programação apresenta o conceito de comentário, que serve para indicar ao compilador (C) ou ao interpretador (Python) que o texto em comentário não deve ser compilado ou interpretado, respectivamente.

Geralmente a linguagem oferece dois modos para comentários, um para comentar apenas o trecho final de uma linha e outro para comentar várias linhas. Os comentário do primeiro tipo em C e em Python usem os símbolos `<cyan>// ignore o restante desta linha</cyan>` e `<cyan># ignore o restante desta linha</cyan>`, respectivamente.
Já os comentários maiores, que sugiro usar apenas nas primeiras linhas de seu código (assim, se houve necessidade de comentar um bloco código poderá fazê-lo, pois não funcionar comentário dentro de comentário), em em C e em Python são respectivamente:
`<cyan>/* Ignore todas as linhas entre estas marcas ... */</cyan>`
`<cyan>""" Ignore todas as linhas entre estas marcas ... """</cyan>`

Vale a pena ressaltar a impossibilidade "comentários dentro de comentário" comparando com o princípio matemática das chaves e parênteses. Quer dizer, uma expressão matemática permite "parênteses dentro de parênteses", como em "`(2 * (3+4))`", mas nem C e nem Python permite que se use comentário dentro de comentário. Exemplifico o erro que resultaria.

1.1 Comentários dentro de comentário não é possível em Python.

Em Python o "comentários em várias linhas" é iniciado com e fechado com a sequência de 3 aspas dupla '`"""`'. Assim, se o programador colocar em seu código Python as próximas 4 linhas:

    <cyan>"""
     Esta e' uma tentativa de colocar comentario dentro de comentario, mas NAO funciona!
     """ Ao encontrar o proximo fecha, ele correspondera' ao primeiro abre, """</cyan>
     logo esta linha NAO mais sera' comentario resultando erro de compilacao!
     Assim, comentarios encaixados NAO sao permitidos!
    """Cód. 1. Código ilustrando o erro ao supor que existe comentários aninhados em Python.

Ao tentar fazer o computador interpretar o código acima, o interpretador indicará o erro, como indicado na figura 1. Experimente em seu interpretador.

      $ python py_teste_comentario.py
      File "py_teste_comentario.py", line 4
      """ Ao encontrar o proximo fecha, ele correspondera' ao primeiro abre, """
           ^

Fig. 1. Ilustração do erro ao supor que existe comentários aninhados em Python.

A razão é que o aninhamento de comentários não existe na configuração padrão Python, assim as 3 aspas da linha 2 fecha o comentário aberto na linha 1, ou seja, não abre um novo bloco de comentários.

Por esta razão recomendo que em seus programas utilize comentários em várias linhas apenas no início do programa (para por exemplo, identificar-se e explicá-lo). Deste modo, fica fácil isolar um bloco grande de seu código (como comentário), o que é útil para encontrar erros de sintaxe (mais simples) ou de semântica.

1.2 Comentários dentro de comentário não é possível em C.

Em C o "comentários em várias linhas" é iniciado com a dupla de caracteres '`/*`' e fechado com a dupla '`*/`'. Assim, se o programador colocar em seu código C as próximas 4 linhas

    <cyan>/* Esta e' uma tentativa de colocar comentario dentro de comentario, mas NAO funciona!
     /* Ao encontrar o proximo fecha, ele correspondera' ao primeiro abre, */</cyan>
     logo esta linha NAO mais sera' comentario resultando erro de compilacao!
     Assim, comentarios encaixados NAO sao permitidos!
    */Cód. 2. Código ilustrando o erro ao supor que existe comentários aninhados em C.

Ao tentar fazer o computador interpretar o código acima, o interpretador indicará o erro, como indicado na figura 2. Experimente em seu compilador.

    $ gcc -o introducao_estrutura_bas.o introducao_estrutura_bas.c
    introducao_estrutura_bas.c:7:2: error: unknown type name ‘logo’
      logo esta linha NAO mais sera' comentario resultando erro de compilacao!
      ^

Fig. 2. Ilustração do erro ao supor que existe comentários aninhados em Python.

A razão é que o aninhamento de comentários não existe na configuração padrão Python, assim as 3 aspas da linha 2 fecha o comentário aberto na linha 1, ou seja, não abre um novo bloco de comentários.

Por esta razão recomendo que em seus programas utilize comentários em várias linhas apenas no início do programa (para por exemplo, identificar-se e explicá-lo). Deste modo, fica fácil isolar um bloco grande de seu código (como comentário), o que é útil para encontrar erros de sintaxe (mais simples) ou de semântica.

2. Uso adequado de "indentação".

Entenda-se por "indentação" o deslocamento horizontal de trechos de código, o que é usado para indicar claramente uma subordinação de comandos (ou aninhamento). Por exemplo, se um comando de seleção "`se`" tiver dois comandos subordinados à ele, pode-se usar 2 espaços em branco a mais nesses comandos subordinados. Veja este exemplo uma linguagem semelhante ao Português:

     se (x>0)
       S = S+1;
       imprima(S);

Para evitar que meus códigos fiquem muito "longos" (não cabendo uma linha inteira na tela), eu utilizo apenas 2 espaços para indicar subordinação (como no extrato de código acima).

Assim, se determinado comando começa na coluna X ("indentação" de X espaços), então todos os comandos subordinados a ele terão deslocamento de ao menos X+2 espaços em branco. Digo "ao menos", pois dentre estes comandos pode existir outras subordinações. Isso é ilustrado no exemplo abaixo, no qual os comandos das linhas 2 até 5 estão subordinados ao "`repita enquanto`", tendo portanto deslocamento X+2 ou mais espaços, mas o comando "`imprima`" da linha 4 tem deslocamento X+4, pois ele está subordinado ao "`se`" que já tinha deslocamento X+2.

A seguir um exemplo com mais linhas e mais subordinações. Nele será usado uma linguagem parecida com o Português, que por isso pode ser denominada Portugol:

    Linha  Código
    1      repita enquanto (cont < N)
    2         imprima(cont)
    3         se ("cont for par") <cyan>// precisa implementar esta condicao, como "cont % 2 == 0"</cyan>
    4           imprima(cont)
    5         incremente(cont)

Note que no código acima, os comandos "`imprima(cont)`" e "`incremente(cont)`" estão deslocados 2 espaços à direita para indicar que ambos estão sobordinados ao comando de repetição "`repita enquanto (cont < N)`" (repetição será explicado em outra aula). Já o comando da linha 4 está subordinado ao comando da linha 3 ("`se`"), por isso o uso do deslocamento adicional de dois espaços em branco.

3. Estrutura básica de um programa em C.

Abaixo ilustro a estrutura básica de um programa em C, utilizando indentação para deixar o código mais claro, o que é importante para você detectar problemas em seu código e essencial para receber uma boa nota por parte do monitor que analisará seu programa.

    <cyan>/*
     O programa abaixo serve apenas para ilustrar a estrutura basica de um programa em C.
     Neste primeiro exemplo existe:
     - Carrega o cabecalho para os comandos (ou funcoes) para entrada e saida de dados: biblioteca "stdio.h"
     - Definicao do codigo principal (por onde devera ser iniciada a execucao de seu codigo): funcao "main"
     - Comandos para leitura e para saida de dados: respectivamente, "scanf" e "printf"
       * Para declarar 2 variaveis que armazenarao valores inteiros, utilizar o "int" como abaixo
       * Para ler valores (usuario digita) e armazenar na variavel usando a funcao predefinida "scanf"
       * O "scanf" deve sempre 2 grupos, o primeiro entre aspas e o segundo uma lista de variaveis precedias do '&'
         dentro das aspas, '%d' indica que o valor lido sera' tratado como inteiro
         na lista de variaveis, o uso de '&' e' obrigatorio para conseguir guardar o valor lido corretamente na variavel
         (experimente eliminar um dos '&' no programa abaixo e veja o que ocorre)
       * O "printf" adota a mesma estrutura do "scanf" com os 2 blocos, mas nele NAO usar o '&' antes da variavel,
         senao sera' impresso o endereco de memoria da variavel, nao o valor que ela guarda)
         O '\n' e' serve para que, apos imprimir "n1+n2", "pular" de linha (ou seja, proxima impressao inicia-se na seguinte)
       * Os formatadores (como '%d') serao explicados noutra aula, eles podem ser usados para imprimir tabelas
    */</cyan>

    <incl1>#include</incl1> <stdio.h> <cyan>// coloque esta linha em TODOS seus programas C (a mesno que ele NAO tenha nem entrada, nem saidas!)</cyan>
    <verm>int</verm> main (<verm>void</verm>) {  <cyan>// obrigatorio em todo programa C (noutra aula explicamos por que usar "void" aqui)</cyan>
      <verm>int</verm> n1, n2;               <cyan>// declarando o uso de 2 variaves para armazenar apenas valores inteiros</cyan>
      <verd>scanf</verd>("%d %d", &n1, &n2); <cyan>// leia 2 valores inteiros, guarde o primeiro em n1 e o outro em n2 (depois veremos '%d' e o '&')</cyan>
      <verd>printf</verd>("%d\n", n1+n2);    <cyan>// imprima um unico valor (soma dos valores guardados em n1 e em n2)</cyan>
      }</stdio.h>

4. Estrutura básica de um programa em Python.

Abaixo ilustro a estrutura básica de um programa em Python, utilizando indentação que deixa o código mais claro e é obrigatório em Python.
Para tentar, desde cedo, indicar aos aprendizes de programação em Python que procurem organizar seus código, sugerimos usar sempre uma função principal, que nominaremos como `main`. Sugerimos que sempre que implementar uma função, faça isso no início de seu código, deixando qualquer declaração de função antes (acima) do trecho que a invoque.

    <cyan>"""
     O programa abaixo serve apenas para ilustrar a estrutura basica de um programa em Python.
     Neste primeiro exemplo existe:
     - Definicao de uma funcao de nome "main": nao e' obrigatorio em Python, mas usaremos desta forma
     - Comandos para leitura e para saida de dados: respectivamente, "input" e "print"
       * Para declarar 2 variaveis que armazenarao valores inteiros, utilizar o "int" como abaixo
       * Para ler valores (usuario digita) e armazenar na variavel usando a funcao predefinida "input"
       * O "input" pode ter um argumento que e' uma mensagem (como 'input("Digite: ")'), mas nao usaremos devido
         ao avaliador automatico (voce nao vera as mensagens e elas poderiam provocar erro na avaliacao)
       * A funcao "int(...)" deve ter como parametro uma expressao numerica, devolvendo a parte inteira dela
         por exemplo, 'int(3.5+2)' devolvera' o valor inteiro 5
       * O "print" serve para imprimir respostas e pode ter como parametros um sequencia de "frase" e expressoes,
         por exemplo, supondo que as variaveis num1 e num2 guardem 2 e 3, o comando
             print(num1,"+", num2, "=", num1+num2);
         No Python 3 resultaria na seguinte impressao na tela
             2 + 3 = 5
         Mas no Python 2, resultaria em uma impressao "menos" elegante
             (2, '+', 3, '=', 5)
       * Existe um modo de impressao mais poderoso, que funciona da mesma forma tanto no Python 2 quanto no 3,:
             print("%d + %d = %d" % (num1,num2,(num1+num2)));
         que sempre resulta na primeira forma acima: 2 + 3 = 5
         Em outra aula sera' explicado o uso de formatadores (como o '%d') para construcao de tabelas.
    """</cyan>
    <verm>def</verm> main () : <cyan># Pode usar outro nome que nao "main", mas convencionaremos "main"</cyan>
      num1 = int(<verd>input</verd>())
      num2 = int(<verd>input</verd>())
      <verd>print</verd>(num1+num2)
    <cyan># note a indentacao dessa linha => NAO pertence ao bloco de comandos da funcao "main"</cyan>
    main()

Leônidas de Oliveira Brandão
http://line.ime.usp.br

Alterações:
2020/08/19: várias pequenas correções, nova seção 1.2 para C (existia uma correspondente apenas para Python)
2020/08/14: novo formato, pequenas revisões
2020/03/31: detalhes
2017/08/08: pesquenos acertos
2017/03/20: segunda, 20 Mar 2017, 17:02