Aprendendo Rust: 04 - Comentários, documentação e tipos de variáveis primitivas
Tags: rust, tutorial
Published: 2020-07-24 16:07:31

E aee jovens, tudo bem com vocês?

Nesta postagem iremos entender sobre comentários, como gerar uma documentação básica do nosso projeto, e alguns tipos de variáveis que podemos usar dentro da _Rust_

Então, lets'go!!!

## Comentários

Comentários são uma forma de documentar nossos programas, mas devemos tentar usar de uma forma moderada, dependendo da situação um nome de função com uma descrição correta do que ela está fazendo é muito mais bem vista do que ser necessário adicionar um comentário pra explicar o que esta função está executando. Os comentários são “ignorados” pelo compilador, eles simplesmente não são executados junto do programa.

_Rust_ tem alguns tipos de comentários, é bem importante saber como a comunidade acaba os utilizando, os _Doc comments_ (comentários para documentação) e os _Nondocs comments_ (comentários que não vão para documentação).

### Comentários para documentação

Todos os comentários para documentação iniciam com 3 caracteres, sendo que o terceiro caractere pode mudar dependendo do tipo de texto que queremos gerar. Abaixo seguem dois exemplos:

```rust
//! Comentario para explicar o modulo, explicar a funcionalidade do projeto
```
```rust
/// Isso é um comentario de funcao para explicar o que a funcao faz
```

### Comentários que não vão para documentação

Vamos ver dois tipos, o comentário de linha e o comentário de bloco que podemos utilizar em múltiplas linhas:

```rust
// Comentario de linha
```

```rust
/*
Este
é um
comentario de bloco
*/
```

Vamos criar um projeto e executar o VS Code com os comandos abaixo no terminal:

```bash
cargo new comments
code .
```

No arquivo _main.rs_ vamos copiar e colar o conteúdo que segue:

```rust
//! Comentario para explicar o modulo, explicar a funcionalidade do projeto
//! Utiliza Markdown
//! # Titulo
//! ## Subtitulo

//! - Isso
//! - eh
//! - incrivel

/// Comentario com 3 caracteres faz parte da documentacao,
/// o terceiro caractere pode mudar dependendo do tipo de texto da documentacao

/// Isso é um comentario de funcao para explicar o que a funcao faz
/// Funcao Principal do projeto
fn  main() {
    // Nondoc comments - comentário que não faz parte da documentação
    // Não é uma boa pratica encher o codigo de comentarios como estou fazendo

    /*
    Tudo aqui
    é um
    comentario
    */

    // Eh mais comumente utilizado pela comunidade
    // o comentario de linha unica
}
```

Cansamos de ouvir “tudo o que é demais pode ser ruim”. Essa premissa vale para comentários, que pode deixar o código poluído, difícil de ler e atualizar. Por isso, tenha bom senso quando comentar as linhas do sistema, colocando textos curtos e somente aqueles que você achar relevante para a leitura e principalmente para a compreensão do código.

 ## Variáveis Primitivas

_Rust_ possui dois tipos de variáveis primitivas, os tipos escalares e os tipos compostos, vamos ver a seguir alguns exemplos:

### Escalares

Vamos começar vendo os tipos de números inteiros:

- `i8, i16, i32, i64, i128` -> A letra _i_ no inicio significa que essa variável é _Signed_, ela possui um sinal, podendo ser positivo ou negativo. O numero após a letra _i_ é a quantidade de bits que essa variável poderá possuir. Por exemplo o tipo `i8` pode armazenar do numero -127 até o 128. 
- `u8, u16, u32, u64, u128` -> A letra _u_ no inicio significa que essa variável é _Unsigned_, possui apenas números positivos o numero após a letra _u_ é a quantidade de bits que essa variável poderá possuir. Por exemplo o tipo `u8` pode armazenar do numero 0 até o 255.

Por padrão quando criarmos uma variável do tipo inteiro sem especificarmos o tipo, a _Rust_ irá inferir o tipo `i32`.

Também existem os tipos de números de ponte flutuante:
- `f32, f64` -> A letra _f_ no inicio significa que essa variável é _float_. O numero após a letra _f_ é a quantidade de bits que essa variável poderá possuir. O tipo `f32` tem uma precisão simples, enquanto o `f64` tem precisão dupla.

Por padrão quando criarmos uma variável do tipo de ponte flutuante sem especificarmos o tipo, a _Rust_ irá inferir o tipo `f64`,  pois nos processadores modernos a velocidade é praticamente a mesma do `f32`, mas possui uma maior precisão.

Para o tipo de caractere temos o:
- `char` -> _Rust_ também trabalha com letras,  `char` vem da palavra _character_. O tipo `char` representa um valor _unicode_, como por exemplo letras com acentuação; ideogramas chinês, japonês e coreano; emoji; e caracteres não visíveis.

E temos o tipo `bool` para representar o tipo lógico -> true (verdadeiro) ou false (falso).

### Compostos

Quando precisarmos guardar uma coleção de valores, utilizaremos um __array__ desta maneira `let array = [1, 2, 3, 4, 5];`. Todos os elementos dentro do _array_ devem ser do mesmo tipo e todo _array_ sempre irá possuir tamanho fixo, não é possível aumentar a quantidade de posições dentro dele.

Para acessarmos os valores de dentro de um _array_ buscaremos de acordo com o índice (posição) do valor `let dois = array[1]`. Este índice começa a contar da __posição 0__ por isso para recuperarmos o valor _2_ usamos o `array[1]`.

Mas e se tentarmos acessar um elemento de uma posição que não existe?
```rust
let array = [1, 2, 3, 4, 5];
let erro = array[20];
```
A compilação será executada com sucesso, mas o programa resulta um erro em _tempo de execução_.

Também possuímos as __tuplas__ onde podemos armazenar vários valores em um mesmo lugar. Diferentemente do _array_, as _tuplas_ podem armazenar valores com tipos diferentes `let tup: (i32, f64, u8) = (500, 6.4, 1);`.

Para acessarmos os valores de dentro de uma _tupla_ temos duas formas:
```rust
let tup = (500, 6.4, 1);
let (x, y, z) = tup;

let quinhentos = tup.0;
let seis_ponto_quatro = tup.1;
let um = tup.2;
```

Da mesma forma que o _array_ o índice inicial da tupla é a __posição 0__;

Vamos criar um projeto e executar o VS Code com os comandos abaixo no terminal:

```bash
cargo new types
code .
```

No arquivo _main.rs_ vamos copiar e colar o conteúdo que segue:

```rust
//! Projeto de exemplo sobre tipos de variáveis

/// Função principal do projeto
fn  main() {
    let signed: i32  =  -10;
    let unsigned: u32  =  5;

	// Para executar o programa remover a linha abaixo
    let unsignedWithErr: u32 = -3; // Vai causar um erro por tentarmos adicionar um numero negativo.
    println!("Integers: {}, {}", signed, unsigned);

    let float: f64  =  -3.14;
    println!("Float: {}", float);

    let sum =  5  +  3; // Soma
    println!("Soma: 5 + 3 = {}", sum);

    let difference =  2.3  -  1.2; // Subtracao
    println!("Subtracao: 2.3 - 1.2 = {}", difference);

    let product =  2  *  5; // Multiplicacao
    println!("Multiplicacao: 2 * 5 = {}", product);

    let quotient =  10  /  5; // Divisao
    println!("Divisao: 10 / 5 = {}", quotient);

    let remainder =  43  %  5; // Resto
    println!("Resto: 43 % 5 = {}", remainder);

    let c: char  =  'R';
    println!("Char: {}", c);

    let is_true: bool  =  true;
    println!("Boolean: {}", is_true);

    let meses = [
        "Janeiro",
        "Fevereiro",
        "Março",
        "Abril",
        "Maio",
        "Junho",
        "Julho",
        "Agosto",
        "Setembro",
        "Outubro",
        "Novembro",
        "Dezembro",
    ];
    println!("Array: {}", meses[0]);

    let tup = (500, 6.4, 1);
    let (x, y, z) = tup;
    println!("O valor de x eh: {}", x);
    println!("O valor de y eh: {}", y);
    println!("O valor de z eh: {}", z);
}
```

Ao executarmos o comando `cargo run` teremos uma saída parecida com:

```bash
Compiling types v0.1.0 (/home/pehdepano/dev/workspace/rust/learning_rust/04 - Doc and Variables/types)
    Finished dev [unoptimized + debuginfo] target(s) in 0.23s
     Running `target/debug/types`
Integers: -10, 5
Float: -3.14
Soma: 5 + 3 = 8
Subtracao: 2.3 - 1.2 = 1.0999999999999999
Multiplicacao: 2 * 5 = 10
Divisao: 10 / 5 = 2
Resto: 43 % 5 = 3
Char: R
Boolean: true
Array: Janeiro
O valor de x eh: 500
O valor de y eh: 6.4
O valor de z eh: 1
```

## Documentação

Para gerarmos uma documentação do nosso projeto ___types___ iremos executar o comando `cargo doc`, e teremos uma saída parecida com:
```bash
Documenting types v0.1.0 (/home/pehdepano/dev/workspace/rust/learning_rust/04 - Doc and Variables/types)
    Finished dev [unoptimized + debuginfo] target(s) in 0.86s
```

Ao acessarmos o caminho `/types/target/types` teremos o arquivo _index.html_ podemos o abrir com o nosso navegador preferido, e teremos uma pagina bem parecida com:

![Imagem](https://i.imgur.com/435AJuv.png)

Vou adicionar o fonte desta postagem no _Github_, segue o link: [Aprendendo Rust](https://github.com/RichardJd/aprendendo-rust)

Quaisquer dúvidas ou sugestões para que eu melhore nas postagens deixe um comentário, e continue acompanhando os próximos posts.

# Referencias

[O livro de Rust](https://doc.rust-lang.org/book/)

[Tour of Rust](https://tourofrust.com/)

[CodeShow](https://www.twitch.tv/codeshow)