Bom Galera, estou trazendo hoje para vocês a continuação da séria de Code Style que começamos a um tempo atrás, e com ela vamos aprender a criar um guia de estilo para padronizar nossos códigos. Lembrando que essa série é voltada para iniciantes e pessoas que estão começando a programar agora e ainda não entendem muito a respeito disso.
No primeiro artigo da série que vocês podem acessar aqui - Code Style - nós falamos um pouco da importância de aprender a fazer um código com um certo padrão na hora de codificar e os benefícios que isso tem para o seu dia a dia tanto pessoalmente quanto profissionalmente.
Caso você não use ou esteja em uma empresa pequena, agência ou até mesmo como freelancer eu convido você a estar criando esse projeto de padrão junto comigo, você é livre para fazer como estou fazendo ou alterar onde você achar que te agrade mais e etc. Uma coisa que tem que ficar em claro pessoal é que não podemos criar um padrão também que foge muito a realizade usada pela comunidade pois isso vai atrapalhar na hora de você se adaptar para uma nova empresa ou contruibuir com um projeto open source.

Um outro post meu também sobre escrita de código eu defendo que independente de você ser um mestre em code style eu acredito sim que você deve escrever código, mesmo que ele não siga padrão ou que ele não fique o mais perfeito possível, afinal para melhorar você precisa errar e para entrar no padrão você precisa primeiro estar fora dele, ou nascer dentro, se você fizer faculdade ou cursos e talz, com certeza isso será passado a você e consequentemente você vai estar já saindo do curso escrevendo direitinho, mas caso você esteja aprendendo sozinho e começando, não tenha medo ou vergonha de ser críticado por isso. Vai ter pessoas que realmente não entendem isso e ao invés de ajudar, vão querer apenas reclamar e brigar por causa do código não estar nos padrões nem performático e mais outros mils problemas, mas o mais importante para você que está começando é, não pare de escrever por causa disso, busque pessoas que estejam dispostas a te ajudar, busque blogs que te ajudem e acima de tudo, estude, evolua e pegue sempre as críticas e tente transforma-las em algo positivo.

Sem mais delongas vamos ao que interessa.

Como eu trabalho mais com Front End, vamos fazer inicialmente a série baseada em front, então não teremos algo sobre php, e outras linguagens de back, ou padrões de comunicação com banco de dados etc. Vamos nos atentar aos 3 pilares do Front. HTML, CSS e Javascript. Hoje começaremos a fazer o padrão através do HTML e junto com o post eu vou estar criando um repositório no github para que quem quiser possa acompanhar, contribuir e com isso melhorarmos nosso guia.

Então pessoal a primeira coisa que vocês precisam saber é que estou baseando o Code Style em alguns links e depois colocarei eles como referência no final do artigo. E esses são só alguns, existe muito mais materiais a respeito disso.

Doctype
A primeira coisa que temos que sempre padronizar pessoal é o uso correto do doctype, atualmente usando HTML5 temos o doctype da seguinte forma.

1
<!DOCTYPE html>

E também pode ser escrita em lower case, aqui vale lembrar que o HTML aceita tanto maiúsculas quanto minúsculas, quando eu comecei a aprender HTML o que eu mais odiava era exatamente ter que escrever todas as TAGs em maiúsculas, mais tarde eu vim descobrir que isso era por causa dos browsers e a forma como eles interpretavam o arquivo e com XHTML também. Então também podemos usar assim.

1
<!doctype html>

Maiúscula e Minúscula
Como falei anteriormente o HTML aceita tanto lowercase ou uppercase (letras minúsculas ou maiúsculas) porém o recomendado é usar sempre lowercases

  • Não é bom usar uma mistura de maiúsculas e minúsculas
  • Tudo em minúsculo é mais fácil de escrever
  • Tudo em minúsculo também deixa o código mais limpo
1
2
3
4
RUIM
<SECTION>
    <p>Este é um parágrafo</p>
</SECTION>
1
2
3
4
MUITO RUIM
<section>
    <p>Este é um parágrafo</p>
</SECTION>
1
2
3
4
RECOMENDADO
<section>
    <p>Este é um parágrafo</p>
</section>

Fechar Tags
Outra recomendação é sempre fechar todas as tags

  • No HTML5 não tem necessidade de fechar as tags, porém é recomendado que seja feito.
  • Até porque as vezes algumas tags que não são fechadas podem quebrar o layout de forma “linda”.
1
2
3
4
RUIM
<section>
    <p>Este é um parágrafo
</section>
1
2
3
4
RECOMENDADO
<section>
    <p>Este é um parágrafo</p>
</section>

Fechar Tags Vazias
Aqui também é recomendado fechar as tags, mesmo que sejam vazias

1
2
3
RECOMENDADO

<meta charset="utf-8">

1
2
TAMBÉM RECOMENDADO
<meta charset="utf-8" />
  • A diferença de usar a BARRA ( “/“ ) é que ela é necessário para o XHTML ou XML então se algum software XML vai acessar sua página é recomendado com a barra.

Letras minúsculas para os nome de atributos

Aqui pessoal vale o mesmo que para as tags, usar letras minúsculas para definir os atributos. Pelos mesmos motivo também.

1
2
3
4
RUIM
<section>
    <p CLASS="text">Este é um parágrafo</p>
</section>

1
2
3
4
RECOMENDADO
<section>
    <p class="text">Este é um parágrafo</p>
</section>

Aspas nos valores de atributos
O HTML5 permite valores sem aspas, porém é recomendado sempre usarmos os valores entre aspas (“”).

  • Você deve usar aspas se o valore tem espaços
  • As aspas facilitam a leitura
  • Sempre mantenha um padrão, sempre use aspas ou nunca use, misturar nunca é uma boa ideia.
1
2
3
4
NÃO FUNCIONA
<section>
    <p class=text special>Este é um parágrafo</p>
</section>
1
2
3
4
FUNCIONA
<section>
    <p class="text special">Este é um parágrafo</p>
</section>
1
2
3
4
RUIM
<section>
    <p class=text>Este é um parágrafo</p>
</section>
1
2
3
4
RECOMENDADO
<section>
    <p class="text">Este é um parágrafo</p>
</section>

Atributos da Imagem
Outro fator muito importante pessoal para os códigos em HTML é o atributo alt das imagens, pois ele será exibido caso e imagem não seja carregada

1
2
RUIM
<img src="endereco/para/imagem.jpg">
1
2
RECOMENDADO
<img src="endereco/para/imagem.jpg" alt="descrição da imagem" >

Outra coisa legal e interessante é que sempre devemos definir um tamanho para a imagem pois isso reduz o tempo de oscilação do browser, fazendo com que ele já reserve o espaço para a imagem antes mesmo dela carregar. Faremos isso com css externo é melhor concentrar os estilos em um lugar só.

Espaços e Sinal de igual
Espaços entre o sinal de igual dos atributos parece bom, porém sem os espaços fica mais fácil de ler e entender o código, prefira assim.

1
2
RUIM
<link rel = "stylesheet" href = "style.css">
1
2
RECOMENDADO
<link rel="stylesheet" href="style.css">

Linhas em branco e identação
Não use linhas em branco sem uma boa razão, de preferência para usar uma linha branca apenas para separar blocos de códigos.
Quanto a identação também, não tem necessidade de identar tudo, apenas os códigos que são dependentes, tipo uma lista ou uma tabela. Utilize sempre 2 espaços para a identação, ou configure o seu editor para que o tab faça 2 espaços, isso deixa mais legível o código

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
IDENTAÇÃO RUIM
<body>

  <h1>Famous Cities</h1>

  <h2>Tokyo</h2>

  <p>
    Tokyo is the capital of Japan, the center of the Greater Tokyo Area,
    and the most populous metropolitan area in the world.
    It is the seat of the Japanese government and the Imperial Palace,
    and the home of the Japanese Imperial Family.
  </p>

</body>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
IDENTAÇÃO RECOMENDADA
<body>

<h1>Famous Cities</h1>

<h2>Tokyo</h2>
<p>Tokyo is the capital of Japan, the center of the Greater Tokyo Area,
and the most populous metropolitan area in the world.
It is the seat of the Japanese government and the Imperial Palace,
and the home of the Japanese Imperial Family.</p>

</body>

EXEMPLO DE LISTA
<ol>
  <li>London</li>
  <li>Paris</li>
  <li>Tokyo</li>
</ol>

EXEMPLO DE TABELA
<table>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
  <tr>
    <td>A</td>
    <td>Description of A</td>
  </tr>
  <tr>
    <td>B</td>
    <td>Description of B</td>
  </tr>
</table>

Comentários

Comentários de uma linha podem ser escritos normalmente, recomenda-se apenas que use um espaço antes e depois das tags de comentário, no final.

1
<!-- Isso é um comentário em uma linha e curto, normal -->

Caso seja mais de uma linha, ou um bloco de comentários, recomenda-se usar da seguinte forma

1
2
3
4
5
<!--
    Aqui vão os blocos de comentários
    Pode ter várias linhas 
    Comentando tudo que for necessário
-->

Meta Data
A tag title é necessária no HTML5, faça um título mais significativo possível.

1
<title>Code Style - HTML5</title>

Para garantir uma interpretação e indexação correta, defina a linguagem e a codificação de caracteres o quanto antes.

1
2
3
4
5
6
<!DOCTYPE html>
<html lang="pt-BR">
<head>
  <meta charset="UTF-8">
  <title>Code Style - HTML5</title>
</head>

Incluindo CSS e Javascript
Essa é a forma que chamamos arquivos de CSS ou Javascript para dentro de nossos arquivos html

1
2
3
4
5
6
7
8
9
10
<!-- External CSS -->
<link rel="stylesheet" href="code-guide.css">

<!-- In-document CSS -->
<style>
  /* ... */
</style>

<!-- JavaScript -->
<script src="code-guide.js"></script>

Lembrando que o CSS normalmente vai ser chamado dentro da tag HEAD e os script antes do fechamento da tag BODY por questões de performance e etc… (posso escrever um post sobre isso futuramente).

Ordem de atributos
Quando for declarar as tags HTML com atributos de prefêrencia para a seguinte ordem:

  • class
  • id, name
  • data-*
  • src, for, type, href, value
  • title, alt
  • role, aria

Por Exemplo:

1
2
3
4
5
6
7
8
9

  
<a class="..." id="..." data-toggle="modal" href="#">
  Example link
</a>

<input class="form-control" type="text">

<img src="..." alt="...">

Atributos boleanos
São atributos que não precisam ser declarados valores, apenas no XHTML teria essa necessidade, porém no HTML5 não é necessário:

1
2
3
4
5
6
7
<input type="text" disabled>

<input type="checkbox" value="1" checked>

<select>
  <option value="1" selected>1</option>
</select>

A presença do atributo já o define como verdadeiro, sendo assim, não necessida declarar ele novamente.

Dicas gerais

  • Evite escrever elementos supérfulos, além de estragar a semantica também dificulta a legibilidade e manutenção do código.
  • Evite escrever linhas maiores que 80 caracteres, para que o seu editor de texto não tenha barra de rolagem lateral.
  • Lembre-se sempre de conversar com a equipe e reavaliar se a ideia e o estilo do código está realmente sendo útil e bom a todos.
  • Sempre mantenha os códigos no estilo escolhido, nunca fuja do padrão escolhido.

Referências:
W3C
http://www.w3schools.com/html/html5_syntax.asp

Google HTML/CSS Style
https://google.github.io/styleguide/htmlcssguide.xml

Codeguide.io
http://codeguide.co/

JetBrains
https://www.jetbrains.com/phpstorm/help/code-style-html.html

Acompanhe no Github

PS: O post demorou a sair pois infelizmente tive umas complicações no trabalho e outras aqui em casa, já que meu filhão está crescendo e agora dorme tão tarde como o pai, e com isso não consigo mais ficar tanto no pc quanto antes, mas o blog continua. :D