Sugestões para convenções na programação de SHELL SCRIPT

AprendiNoLinux
(usa Ubuntu)

Enviado em 06/08/2011 - 11:47h

Sou iniciante em desenvolvimento de SHELL SCRIPT e no geral rsrs.

Estou iniciando o aprendizado e vou compartilhar o trabalho com uma equipe de
6 desenvolvedores que trabalham em PHP, MYSQL, e C.

Minha missão é desbravar o caminho ANTES (boi de piranha) montando código que
será compartilhado pelo restante da equipe.

Embora as convenções não sejam OBRIGATÓRIAS no mundo do desenvolvimento, é uma
boa prática adotar padrões já utilizados para facilitar reaproveitamento de
código, documentação e aprendizado.

No meu caso não tenho opção rsrs, tenho que tentar fazer o melhor no adoção dos
conceitos e eles serão seguidos pela equipe após aprovados.

Gostaria de receber um feedback de todos que aceitarem participar.

A comunidade pode fazer como sempre fez, mas a nossa equipe tentará adotar este
padrão que irei tentar com a ajuda dos demais, definir.

Tudo que for deixado de lado agora poderá ser completado é claro, mas se for
feito antes enquanto não tenho nada, melhor.

Vou ficar responsável pelas documentações e sou eu que vou sofrer caso
alguma coisa importante fique de fora.

Um colaborador do VOL sugeriu que o código e os texto fiquem em 80 caracteres
e já estou adotando isto como exemplo ao digitar este texto, rsrs.

Só pra entrar no clima.
Segue abaixo algumas convenções minimalistas já elaboradas e seguidas por mim.
============ INICIADO abaixo =================================================

#!/bin/bash
#
# - Faz acesso exclusivo a um determinado arquivo e atualiza seu contador.
#   retorna info do contador e dispara processos em arquivos.
#   Esta rotina tem a finalidade de eliminar serviços residentes no cron.
#   Hoje temos mais de 350 serviços no cron e isto é insustentável.   
#------------------------------------------------------------------------------
# name:   CheckContador.sh
# since:  2011-08-04 17:58 (GMT -03:00)
# author: Geraldo T. Albuquerque - Twitter: @AprendiNoLinux
# more:   http://aprendinolinux.wordpress.com/ 
#
###############################################################################
# TODO: Script de estações até solucionar controle de processos remotos.
# -----------------------------------------------------------------------------
# XXX: Cenário ideal: Serviço roda no servidor e verifica pasta virtual ssh.  
# Cada estação deve fazer solicitações de contadores. 
# Serviço rodando no server deve fazer processamento e devolver retorno. 
# Estações recebem retorno e executam seus processamentos.
# São mais de 50 máquinas que tentam acesso a vários arquivos de contadores.
# -----------------------------------------------------------------------------
# TODO - Indica uma tarefa a ser feita ou pendência.
# FIXME - Use para indicar um bug conhecido e precisa ser arrumado
# XXX - Enviar um recado importante no ponto.
# -----------------------------------------------------------------------------
# Convenções padronizadas no Script. Padrao.txt contém todas as convenções.
# -----------------------------------------------------------------------------
# Variáveis GLOBAIS serão MAIÚSCULAS. Se forem liga desliga 0=desliga 1=ligado.
# Variáveis locais ou temporárias sempre em minúsculo. "_" separa nomes.
# Nome de função sempre iniciar com "_" e capitalizada ex: _MinhaFuncao()
# Dentro das funções, sempre definir a variável como local ao nomea-las. 
# Sempre incluir pelo menos as opções -h, --help, -v, -V, e -q  
# -----------------------------------------------------------------------------
# Qualquer Alteração efetivada deve ser notificada no Alteracoes.txt. 
# A cada NOVA versão deve ser atualizado o arquivo Noticias.txt 
# Registrar em Noticias.txt os créditos de contribuidores da versão.
# 
# -----------------------------------------------------------------------------
### 
 

============ FINALIZADO acima =================================================


O arquivo Padrao.txt irá conter todas as sugestões de forma detalhada para cada
tipo de trabalho. Desde a criação de variáveis lógicas, chaves, textos, scopo.
Formas estruturadas para a passagem de parâmetros a scrips externos de outras
linguagens e para funções internas ou bibliotecas genéricas de funções.

Em alguns casos, o arquivo Padrao.txt não será seguido, porém tentaremos ao
máximo implementar seu uso dentro de nossa equipe.
-------------------------------------------------------------------------------
Alteracoes.txt será o arquivo de changelog contendo todas as alterações feitas.
Para este arquivo, um mínimo de convenção também será adotado.
-------------------------------------------------------------------------------
Noticias.txt deverá conter de forma convencionada os detalhes importantes da
versão liberada. É fundamental dar destaque aos colaboradores que de alguma
forma participaram do desenvolvimento.
Válido TAMBÉM para quem realiza importantes testes e encontra BUGS.(erros)
-------------------------------------------------------------------------------

Conforme os enunciados acima, aguardo qualquer contribuição ou material
relevante para que eu possa seguir em frente nesta jornada.

Obrigado antecipadamente pela colaboração de todos.

GA

removido
(usa Nenhuma)

Enviado em 06/08/2011 - 14:43h

Atente para as 80 colunas. Seu código está esta ultrpassando o frame de postagem
do VOL
Veja este exemplo de um arquivo de inclusão. É apenas uma sugestão... 8D



# package: Matematica
# file: operacoesBasicas.include.sh
# Efetua operações basicas com 2 numeros inteiros.
# + Retorno do resto de uma divisão.
# - Validação de parametros ainda não implementada.
#
# date: 2011-08-04 23:58 (GMT -03:00)
# + Adicionada a capacidade de retornar o resto da divisão
# version: 1.1b
# autor: autor do release [ link ]
#
# since : 2011-08-03 23:58 (GMT -03:00)
# version: 1.0b
# autor: autor do release [ link ]
#
# charset: UTF-8
# end line: Linux
# more: http://sekysu.blogspot.com - onde posso achar informações adicionais sobre este código
# licenses:


# - soma dois numeros
function _somaDoisNUmeros()
{
#
}



Acredito que você saberia facilmente terminar o resto do código. 8D
Boa sorte!!!

Note que no cabeçalho principal informei o nome do pacote principal e escrevi
resumidamente sobre os REQUISITOS que todo o código - o arquivo com funções, include -
deve resolver. Também adicionei um comentário muito breve sobre o unico release.

Das tags date até a tag since são os blocos descritores dos releases em ordem
remissiva.

Nos procedimentos eu escrevi um comentário sobre eles.

Perceba que os comentarios parecem pleonasmos - óbvios desnecessários. Essa é a para mim a
prova que o código esta bem escrito - legibilidade humana alcançada.

AprendiNoLinux
(usa Ubuntu)

Enviado em 06/08/2011 - 17:43h

Obrigado pelo feedback inicial @ronin seguindo...

Já adotei no arquivo Padrao.txt que estou montando o uso de 80 colunas :) Se no exemplo acima escapou é porque estava digitando aqui como exemplo e falhei rsrs.

Uma boa prática que uso no php é descrever o nome do arquivo que só tem propósito de inclusão nomeado com include ou algo relacionado.
Fazer a composição do nome do arquivo e das funções de forma bem descritiva ajuda aos outros que irão trabalhar no código. Estou lendo vários artigos do VOL e de outros locais para ir montando o básico para um padrão consistente. A vantagem de elaborar um padrão é que os desenvolvedores que irão usa-lo não tem "QUASE" nenhum vício em Shell Script. Quebrar a barreira de outras linguagens é também um desafio. Já usam parcialmente convenções e documentar não é o forte na maioria dos desenvolvedores.


[citando]
# package: Matematica
[/citando]

Vou adotar até para poder usar algum script que faça as leituras de cabeçalhos e gerar algum tipo de documentação. Se tiver algum Shell Script ou ferramenta que gere a documentação com base nos cabeçalhos seria útil. Ainda não procurei a respeito. Estou apenas coletando informações sobre as melhores práticas relacionadas ao desenvolvimento de Shell Script e seus "padrões" mais utilizados. A ideia não é criar nada novo. Precisamos ter um caminho consistente pois acho que teremos vários pequenos Shell Scripts e outros nem tão pequenos que estarão de alguma forma se integrando.

[citando]
# file: operacoesBasicas.include.sh
[/citando]

Vou adotar este esquema também. O nome do arquivo e a divisão com o . (ponto) permite uma seleção natural e muito intuitiva.

[citando]
# Efetua operações basicas com 2 numeros inteiros.
# + Retorno do resto de uma divisão.
# - Validação de parametros ainda não implementada.
#
[/citando]

Perfeito. No exemplo inicial no 1° tópico, tentei fazer igual. Se entendi bem, o (+) informa um retorno da função. (-) seria para validações necessárias ?
Independente dos sinais, a descrição está objetiva, curta e clara. Qualquer outra informação eu estarei colocando no arquivo LEIAME.txt que por "esquecimento" não foi incluído, rsrs.

[citando]
# date: 2011-08-04 23:58 (GMT -03:00)
# + Adicionada a capacidade de retornar o resto da divisão
# version: 1.1b
# autor: autor do release [ link ]
#
[/citando]

Tranquilo, já estou adotando este esquema também. Sobre o ChangeLog dentro do próprio arquivo eu acho que vou usar só as últimas.
Deverei adotar algo como:

#: + adicionado x, y z
#: = alterado
#: - removido
#: : Info extra no Alteracoes.txt
#: : Info Geral veja o Leiame.txt

Até o (#:) é significativo para tratamento do cabeçalho. Deverá determinar conteúdo a ser lido caso eu não encontre um programa p/ gerar documentação.

[citando]
# since : 2011-08-03 23:58 (GMT -03:00)
# version: 1.0b
# autor: autor do release [ link ]
#
[/citando]

Já estou adotando integral este modelo. Esqueci o version, mas no Padrao.txt já fiz a inclusão para usa-lo.

[citando]
# charset: UTF-8
# end line: Linux
# more: onde posso achar informações adicionais sobre este código
# licenses:
[/citando]

Bem lembrado. Vou adotar este modelo e incluir no Padrao.txt
Sobre licenses, geralmente será GPL. Mesmo quando compiladas para uso em áreas hostis (usuários malucos finais de empresas rsrs.)
Qual o melhor modelo de licenses GPL para Shell Script ?

[citando]
# - soma dois numeros
function _somaDoisNUmeros()
{
#
}
[/citando]

Já adotando o padrão (_) para prefixo de função como sugerido. Noto que o primeiro nome está em minúsculo e o restante capitalizado. Sem problemas, vou procurar adotar o mesmo padrão. So o nome da função, está perfeito. O nome diz tudo sobre o que ela se propõe.

[citando]
Acredito que você saberia facilmente terminar o resto do código. 8D
[/citando]

Tá pedindo muito rsrs. Ainda não, mas estou aprendendo. :)

[citando]
Boa sorte!!!
[/citando]

Boa não rsrs, você e os demais que estão fazendo as sugestões e críticas são bem vindos a continuar colaborando e palpitando. Estou tentando fazer este processo em comunidade e democraticamente dentro do possível.

[citando]
Perceba que os comentarios parecem pleonasmos - óbvios desnecessários. Essa é a para mim a
prova que o código esta bem escrito - legibilidade humana alcançada.
[/citando]

Penso que nem sempre o código pode ser tão descritivo. Se educar o desenvolvedor a documentar usando padrões bem definidos, ele será obrigado a fazer o código tão descritivo quanto possível. Afinal, hoje sou pedra, amanhã vidraça. Nunca gostei de documentar programas e agora estou na lama fazendo o que sempre detestei e paguei caro por isto. Alterar código 2 ou 3 anos depois só tentando descobrir o que faz as rotinas é super "XXXiqueeeeeee" rsrs.

Por favor, quero lembrar que todos podem participar dando sugestões, exemplos, links criticas. Vou melhorando este material e quando estiver razoável, vou enviar aqui antes.

Se ele será útil para todos na comunidade eu não sei, mas será um prazer participar fornecendo este meu aprendizado que deverá ser útil a outros novatos. Hoje meu maior tempo esta sendo gasto nas pesquisas de artigos, Scripts, dicas. Não encontrei um local centralizado sobre a melhor prática no desenvolvimento de Shell Scripts aqui. Mesmo o livro do Aurelio (Shell Script Profissional) e do Julio Cezar (Programação Shell Linux 5ª edição), não cobrem totalmente os padrões. Fazem boas referências de algumas boas práticas.

Contando com a colaboração dos Shelleiros...

Obrigado

GA

ps: Antes que alguém pergunte porque investir tanto tempo nesta preocupação de documentar eu já vou responder. Hoje a velocidade das mudanças são enormes. Muitas interações podem ser feitas rapidamente em Shell Script. Fui obrigado a entrar neste mundo rsrs. Digamos que seria especializar a gambiarra ? Não. Garantir que não serão gambiarras e sim programas. Se costuma chamar de Scripts porque são descartáveis ou de uso provisório. Tem exemplos de Scripts que já estão sendo usados a mais de 5 anos. Pra mim isto é programa, sistema, aplicativo. :) Minha opinião pessoal.

AprendiNoLinux
(usa Ubuntu)

Enviado em 06/08/2011 - 22:33h

Versão para sugestões e críticas. Comentários no final.


============ INICIADO exemplo abaixo. Opção profs =============================

#!/bin/bash
#
#: package: Acessos (nome de exemplo p/ Script ou executável final) (***)
#: file: CheckContador.sh (Do Script atual)
#: since: 2011-08-04 17:58 (GMT -03:00)
#: author: Geraldo T. Albuquerque - Twitter: @AprendiNoLinux
#: co-author: Meu chefe mesmo sem fazer porra nenhuma. ;) opcional (***)
#: contributors: créditos a colaboradores (***)
#: site: http://aprendinolinux.wordpress.com/ (propaganda a desgraça do negócio) 
#: version: 1.0b (atual release.)
#: download: [link para baixar a versão atual] 
#: support: [Link para local de suporte] (***)
#: e-mail: canabrava@sotomandouma.com.br (***)
#------------------------------------------------------------------------------
#: objectives: Resumo prático e rápido sobre o Script. De 1 a 5 linhas.
#------------------------------------------------------------------------------
#: features: Alguma coisa miraculosa que inventou a roda. (***)
#: + retorna info do contador e dispara processos em arquivos.
#: + Verifica status do usuário.
#: + Alerta sobre sobrecarga nos contadores.
#------------------------------------------------------------------------------
#: comments: Comentários que julgar útil e até agradecimentos. 
#:
#:
#------------------------------------------------------------------------------
#: charset: UTF-8
#: end line: Linux
#: more: Veja Acessos.leiame.txt Acessos.alteraçoes.txt Acessos.ajuda.txt 
#: dependencies: Caso exista algum dependência informe. (***)
#: Language: Default: lang.acessos.pt_br , lang.acessos.en (***)
#  (***) = opcionais
#------------------------------------------------------------------------------
#--Se o Script for em um único arquivo usar changelog interno------------------
#: changelog: Mesmo externo, informe sobre a última versão aqui.
#: date: 2011-08-04 23:58 (GMT -03:00)
#: + Adicionada a capacidade de errar na divisão
#: - Removido teste da dentadura.
#: [fixed] Trocado o programador.
#: [changed] Alterado ou melhorado algum funcionamento anterior. 
#: version: 1.1a
#: autor: autor do release [ link ] (Pode ter autor diferente entre versões.)
#:
#: date: 2011-08-06 08:12 (GMT -03:00)
#: + Adicionada a capacidade de retornar o resto da divisão
#: - Removido teste de hora.
#: [fixed] algum bug relatado e corrigido.
#: [changed] Alterado ou melhorado algum funcionamento anterior. 
#: version: 1.1b
#: autor: autor do release [ link ] (Pode ter autor diferente entre versões.)
#: ps: Manter links de versões anteriores é uma responsa danada rsrs. 
#------------------------------------------------------------------------------
#: WARNING! downloading or installing the Software, you is responsable for all
#: problem. Cannot guarantee that no harm will be done to your computer or 
#: you operating system, ... blá blá blá.... La garantia sou jô :) 
#:
###############################################################################
#: TODO: Script de estações até solucionar controle de processos remotos.
#------------------------------------------------------------------------------
#: XXX: ALERTA: Serviço roda no servidor e verifica pasta virtual ssh. 
#: Cada estação deve fazer solicitações de contadores. 
#: Serviço rodando no server deve fazer processamento e devolver retorno. 
#: Estações recebem retorno e executam seus processamentos.
#: São mais de 50 máquinas que tentam acesso a vários arquivos de contadores.
#------------------------------------------------------------------------------
#: TODO: Indica uma tarefa a ser feita ou pendência.
#: FIXME: Use para indicar um bug conhecido e precisa ser arrumado
#: XXX: Enviar um recado importante no ponto.
# ------Fim das convenções. Abaixo resumo do Padrao.txt -----------------------
# Convenções padronizadas no Script. Padrao.txt contém todas as convenções.
# -Incluído abaixo mas ficará no Padrao.txt, só pra lembrar -------------------
# Variáveis GLOBAIS serão MAIÚSCULAS. Se forem liga desliga 0=desliga 1=ligado.
# Variáveis locais ou temporárias sempre em minúsculo. "_" separa nomes.
# Nome de função sempre iniciar com "_" e capitalizada ex: _minhaFuncao()
# Dentro das funções, sempre definir a variável como local ao nomea-las. 
# Sempre incluir pelo menos as opções -h, --help, -v, -V, e -q 
# -----------------------------------------------------------------------------
# Qualquer Alteração de código efetivada notificar no Acessos.alteracoes.txt. 
# A cada NOVA versão deve ser atualizado o arquivo Acessos.noticias.txt 
# Registrar em Noticias.txt os créditos de contribuidores da versão.
# Informações a outros desenvolvedores estarão no leiame.txt 
# Informações a usuários estarão no arquivo Ajuda.txt 
# ex: Acessos.ajuda.txt - Acessos.leiame.txt - Acessos.alteracoes.txt
# arquivo Padrao.txt contém todas as infos sobre as convenções.
# -----------------------------------------------------------------------------
# ps: Trocar nomes em português nos docs esta no escopo. 
#     Acessos.ajuda.txt p/ Acessos.help.txt - dependerá das configs.
#     Vai doer a 1ª vez, mas se for padronizado é 100% reaproveitável.
### 
 

============ FINALIZADO acima =================================================

Cabeçalho mínimo. Para Shell Script temporário mesmo. Vida curta ou simples.
Geralmente o script tem apenas um único arquivo e nada mais.
Descontração: "meia boca", preguiçoso ou simplório como queiram.
Calma que é só brincadeirinha rsrs.
============ INICIADO abaixo ==================================================

#!/bin/bash
#
#: file: CheckContador.sh (Do Script atual)
#: since: 2011-08-04 17:58 (GMT -03:00)
#: author: Geraldo T. Albuquerque - Twitter: @AprendiNoLinux
#: site: http://aprendinolinux.wordpress.com/ (propaganda a desgraça do negócio) 
#: version: 1.0b (atual release.)
#: download: [link para baixar a versão atual] 
#------------------------------------------------------------------------------
#: objectives: Resumo prático e rápido sobre o Script. De 1 a 5 linhas.
#------------------------------------------------------------------------------
#: charset: UTF-8
#: end line: Linux
#------------------------------------------------------------------------------
#: changelog: O que eu lembrei eu marquei o resto só eu e Deus sabemos.
#: date: 2011-08-04 23:58 (GMT -03:00)
#: + Adicionada a capacidade de errar na divisão
#: - Removido teste da dentadura.
#: [fixed] Trocado o programador.
#: [changed] Alterado ou melhorado algum funcionamento anterior. 
#: version: 1.1a
#: autor: autor do release [ link ] (Pode ter autor diferente entre versões.)
#:
#: date: 2011-08-06 08:12 (GMT -03:00)
#: + Adicionada a capacidade de retornar o resto da divisão
#: - Removido teste de hora.
#: [fixed] algum bug relatado e corrigido.
#: [changed] Alterado ou melhorado algum funcionamento anterior. 
#: version: 1.1b
#: autor: autor do release [ link ] (Pode ter autor diferente entre versões.)
#------------------------------------------------------------------------------
#: ps: Descontraindo. Link de suporte ? e-mail ? Empresa ? Salve-se quem puder. 
#: WARNING! La garantia soi Jô meu cumpadre. Pode usar sem medo em ser feliz.
#: Qualquer problema, vá no forum http://www.vivaolinux.com.br/ e reze. 
 

============ FINALIZADO acima =================================================

Além da ajuda que já estou recebendo, faço questão de citar as fontes de
pesquisa que estou fazendo.

1) Livro do Aurélio Marinho Jargas (SHELL SCRIPT profissional) http://www.aurelio.net
2) Livro do Julio Cezar Neves ( Programação SHELL LINUX ) http://www.julioneves.com
3) Artigos do @albertguedes (Albert Guedes) , exemplo: http://www.vivaolinux.com.br/artigo/Coloque-ordem-em-seus-programas/?pagina=2
4) Artigos do @tenchi (Leandro Santiago) vários, exemplo: http://www.vivaolinux.com.br/artigo/Alguns-recursos-do-BASH-para-voce-utilizar-em-seus-programas/
5) Não tem atualizações recentes, mas muito bom para consulta: http://thobias.org/doc/shell_bd.html
6) Tem tudo sobre o tema, mas pouca coisa relacionada a padrões: http://www.gnu.org/software/bash/manual/bashref.html
7) @ronin (Paulo Riceli Dias Lelis), vários, exemplo: http://www.vivaolinux.com.br/artigo/Introduzindo-um-pouco-mais-a-fundo-o-shell-script-(revisado)
8) @bryan (Bryan Garber da Silva), exemplos: http://www.vivaolinux.com.br/artigo/As-maravilhas-do-Shell-Script
9) Vários materiais do livro e dicas: http://wiki.softwarelivre.org/bin/view/TWikiBar/TWikiBarPapo005
10) @vodooo (Eduardo Vieira Mendes) - exemplo: http://www.vivaolinux.com.br/artigo/Prompt-Bash-avancado/
11) http://www.gnu.org/software/bash/manual/bashref.html
12) http://www.tcsh.org/FAQ
13) http://sourceforge.net/projects/zsh/files/zsh-doc/4.2.7/
14) @Caiapo (Wesley Caiapó) Shell Script / Kommander
15) http://www.hardware.com.br/livros/ferramentas-linux/capitulo-programando-shell-script.html
16) @capitainkurn (Carlos Affonso Henriques) - http://www.vivaolinux.com.br/dica/Conhecendo-o-test
17) @rogerboff (Roger Pereira Boff) - Cli-Apps.org - Repositório de shell scripts
18) E tantos outros que não anotei os participantes e links dos materiais.
19) @rai3mb (Raimundo Alves Portela) http://www.vivaolinux.com.br/script/Operacoes-com-valores-em-arquivo-texto


Poderá perceber que poucos tratam da questão sobre a padronização e convenção da codificação. Se pintar um livro especial sobre o tema eu compro na hora :)

Por que documentar o código se só eu vou ver ?

Grande engano meu caro jedi (que não é o projeto java de desenvolvedores a distância rsrs), mas sim todo desenvolvedor que luta contra o tempo por demorar muito pra entender o que ele mesmo codificou a 6 meses, 1 ano ou 2 anos atras.

Fora a questão da codificação do próprio, tem outros desenvolvedores ou usuários que irão usar o código e em algum momento podem precisar fazer alterações. Entender a lógica de cada etapa do programa que outro fez não é fácil. Entender os comandos é outra coisa. Entender o que ele pensava quando nomeou uma variável de A e outra de Z é outros quinhentos.

Como diz Roberto Carlos, detalhes tão pequenos de nós dois... Mas que fazem as pessoas perderem os cabelos.

A proposta.

Tentar fazer algo junto colaborativo requer um mínimo de coesão e convenção. Quem já participou de grupos de desenvolvimentos Open Source sabe que os padrões embora as vezes podem engessar, por outro lado ajudam a colaboração de terceiros e juntos fazem a força motriz do software livre.

Sinceramente, estou perdido com tantas diferenças na forma que o pessoal tem escrito os Scripts para as mesmas finalidades e de formas totalmente diferentes. Nada contra, a criatividade do desenvolvedor é liberada. Não estou falando em impor padrões. Estou falando em usar de forma minimalista que seja certos conceitos que a maioria AS VEZES USA e nem todos adotam.

Desculpas que eu sempre usei:

- Amanhã eu arrumo o nome destas variáveis.
- Quando terminar eu vou lembrar de todas as alterações para o changelog.
- Não precisa colocar em função só vou usar este código aqui.
- Esta mensagem nunca mais vai ocorrer em ponto algum, só aqui. Se alterar, dou um jeito.
- Não tenho tempo pra ficar explicando o que este loop vai fazer. Qualquer um sabe ler o que eu fiz.
- Este for tá muito claro. Só não entende quem não sabe programar. (Perdi quase 3 horas pra entender porque o for não fazia o que se propunha junto com outro loop.)
- Só vou usar este Script durante um mês então vai ficar assim mesmo. Jesus, já passaram 3 anos. E o danado já foi demitido e agora José ?
- Meus programas são limpos e o código é totalmente legível. Sei, entendi. Pra que serve mesmo esta função x_obj_2 ? Ahh é pra... deixa eu pensar....
- Tenho o maior trabalho pra documentar tudo certinho e depois ninguem lê. Vou parar de documentar. Ohhhh desculpa fuleira...
- Pô vou ficar fazendo tudo mastigado ? Quando eu preciso pego cada código lascado sem nada. - Claro, se todos fizerem o mesmo tá todo mundo lascado.

Emprego novo, tudo novo. :)

Mostrar serviço ?

Não, preparar o futuro. Outros programadores poderão se beneficiar destas convenções.

Quem ?

Não importa. Eu fiz a minha parte.

É neste espírito que estou convocando quem quer participar fornecendo dicas e materiais relevantes para um bom esquema de convenções e documentação especializado para SHELL SCRIPT.

Vai dizer que está cheio de livros que falam sobre padrão de codificação ? Claro, tem mesmo. Pra VB, C, Java, PHP, Python, etc.. etc..

Pra codificar a maioria serve. Para documentar em código a maioria serve. Para fazer os logs de alterações a maioria serve.
Então por que não usam os padrões convencionados nos livros ?

Eles são diferentes....

Diferentes ?

Sim e não. De qualquer forma, dentro da linguagem eles tem um relativo padrão de codificação e documentação. O SHELL SCRIPT também. De tanto olhar os códigos recentemente, percebi que existem vários padrões. Cada um usa um pouco de cada. Adota quando sente vontade. Isto não vai mudar. A minha intenção é que seja possível compartilhar um padrão ideal. Se não quer usar todos, que saiba pelo menos quais são estes padrões e adote aquilo que desejar.

Obrigado pela atenção e por me alongar tanto no assunto. Penso que poderá sair algo legal e produtivo se ajudarem. Fazer sozinho é chato rsrs.

GA.

AprendiNoLinux
(usa Ubuntu)

Enviado em 07/08/2011 - 12:26h

Feedback necessário para inclusão de variáveis úteis quando se carrega o SHELL que podem ser de uso geral.
Para ser incorporado em biblioteca de função de múltiplo uso.
Poderá ser usada independente também.

#!/bin/bash
#
#
#: package: biblioteca.includes.sh (***)
#: file: ambiente.bash.include.sh
#: since: 2011-08-07 11:18 (GMT -03:00)
#: author: Geraldo T. Albuquerque - Twitter: @AprendiNoLinux
#: version: 0.01 Alfa 
#------------------------------------------------------------------------------
#: objectives: Capturar o ambiente primário do usuário no bash
#------------------------------------------------------------------------------
#: comments: coleta o máximo de infos do bash do usuário. 
#:           Qualquer variável especial de aplicativo não é neste local.
#:           Arquivo pode ser reaproveitado em vários Scripts.
#------------------------------------------------------------------------------

function _ambiente.bash {

# Contém o editor preferencial, ex: nano, mcedit, etc...
_EDITOR="$EDITOR" 

# Contém o caminho completo ao home do usuário. 
_HOME="$HOME" 

# LANG=Idioma e codificação, exemplo: pt_BR.UTF-8  
# LANGUAGE=Sigla do idioma usado e o inglês, ex: pt_BR:en
_LANG="$LANG" 
_LANGUAGE="$LANGUAGE" 

# Diretório atual PWD formato: /home/administrador/v1
# Diretório ANTERIOR formato: /home/administrador
_DIRETORIO_ATUAL="$PWD"  
_DIRETORIO_ANTERIOR="$OLDPWD" 

# Caminho PATH, formato: /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin
_PATH="$PATH" # 
_PATH_SHELL="$SHELL" #/bin/bash

# PID do AGENTE ativo de SSH, formato: pid NNNN
_SSH_AGENT_PID="$SSH_AGENT_PID" 

# Nome do usuário conectado, USER ou USERNAME, ex: meunome
_USER="$USER" 
_USERNAME="$USERNAME" 

# Qual o Id do usuário atual. Nas duas formas básicas. Se 0 (zero) é root.
_USER_ID=$(id -u)
_USER_UID="$UID" 

# Linhas definidas para uso de histórico.
_LINHAS_DE_HISTORICO="$HISTSIZE" # 500

# HOSTNAME ou nome da máquina. 
_HOSTNAME="$HOSTNAME" 

# Controle de separador padrão do shell. Cuidado com esta variável.
# Para atribuir novo valor: IFS=: ( padrão normal é: ' \t\n' )
# Após usar, lembrar de retornar ao original: IFS="_IFS_ORIGINAL"
_IFS_ORIGINAL="$IFS"    

# Salvando SO real. Não é a distribuição, formato: linux-gnu
_OSTYPE="$OSTYPE" 

}

_ambiente.bash

return

#------------------------------------------------------------------------------
#: Notas: Que outras infos de ambiente importantes para estar aqui.
#: FIXME: Falta variável que indica qual é a distribuição usada.
#: TODO: Endereço completo de acesso será passado pelo pacote de biblioteca.
#: XXX: ATENÇÃO, não usa biblioteca? Coloque este no diretório de seu Script.
#------------------------------------------------------------------------------
 

Pendências conhecidas:

1) falta aplicação de parâmetros.
2) Validar solicitações de escopo para retornar valores de ambiente padronizado.
3 ) Falta exemplo de uso prático.
4 ) Passar PATH para array de diretórios.
5 ) Passar LANGUAGE para array.
Sugestões ?

GA

AprendiNoLinux
(usa Ubuntu)

Enviado em 07/08/2011 - 23:14h

Continuando o desenvolvimento, chegou a hora das configs.

2ª parte: Pastas de trabalho para o aplicativo.

Sugestões continuam sendo bem vidas. Fique tranquilo, perguntar não ofende !!! rsrs
================= iniciando abaixo ===========================================
EDITADO: Troquei o arquivo anterior por este atualizado em 08-08-2011

#!/bin/bash
#
#: package: Acessos (nome de exemplo p/ Script ou executável final) (***)
#: file: config.pastas.sh 
#: since: 2011-08-08 22:18 (GMT -03:00)
#: author: Geraldo T. Albuquerque - Twitter: @AprendiNoLinux
#: site: http://aprendinolinux.wordpress.com/ (propaganda desgraça do negócio) 
#: version: 0.02 ALFA (atual release.)
#------------------------------------------------------------------------------
#: objectives: Definir todas configurações de diretórios dos aplicativos. 
#------------------------------------------------------------------------------
#: features: Modularizando as configurações. (***)
#: TODO Precisa ser feito os verificadores dos diretórios. 
#: XXX Padrão de variáveis precisa ser melhorado. Verificadores irão falhar.
#: FIXME Não verifica as dependências para receber valores.
#------------------------------------------------------------------------------
#: comments: Onde eu fui me meter.  
#:           
#------------------------------------------------------------------------------
#: charset: UTF-8
#: end line: Linux
#------------------------------------------------------------------------------
# Todas as variáveis de controle de diretórios serão movidas para
# arquivo especial de CONFIGS.
# Serão separadas em 2 tipos de arquivos.
# As variáveis também estão sendo feitas para serem portáveis.
# Se alguém tiver uma opção melhor, é sempre bem vindo para opinar.
#------------------------------------------------------------------------------

# Faz teste se a variável e o caminho do diretório existem.
# Se for desconhecido, pode ter sido chamado isoladamente.
# Vai avisar e abortar.
if test -e "$_HOME" ; then
	:
else
	echo "Vairável OBRIGATÓRIA _HOME não foi definida, verifique !!!"
	echo "Não pode carregar este arquivo sem as definições de AMBIENTE."
	read -t 5
	exit
fi
# TODO: Desenvolver função de teste para arquivos e diretórios.
#       Usar em todas configs.
#       Parâmetros (V=verificar ou (C)=Criar)

function _config.pastas {

# Raiz do diretório absoluto para todos arquivos temporários.
# Qualquer diretório temporário será criado abaixo dele.
# Caso não exista, diretório será criado.
CONF_TMP="${_HOME}/tmp"
DIR_TMP="${CONF_TMP:-${HOME}/tmp}"

# Local onde estarão todos arquivos para a instalação dos Scripts.
# Para facilitar a base de testes, local padrão ao BASE. 
# Quando finalizado, o instalador irá fazer o seu trabalho e irá solicitar
# o local de instalação ao usuário final.
DIR_INSTALL="/TESTES"

# Local base para alocação das caixas de comunicação.
DIR_BASE="/TESTES"

# Local base onde irã ficar os Scripts personalizados.
# Cada tipo de aplicação deverá ter o seu próprio diretório para os Scripts.
# Muitas vezes poderá ser o próprio diretório do DIR_BASE.
# Note, a pasta de SCRIPTS é idenpendente de onde está sendo feito o trabalho.
DIR_SCRIPTS="/TESTES/SCRIPTS"

# Local onde ficarão todas as bibliotecas reaproveitáveis de código.
# Todos Scripts deverão compartilhar este endereço. 
# Para o desenvolvimento, a variável está em sub-diretório do DIR_BASE
# Será movida futuramente após liberação da versão a outro local.
# Não tem importância o local onde estão os outros Scripts.
# As bibliotecas não precisam saber de seus diretórios.
# Quem precisa saber são os Scripts. 
# Bibliotecas poderão verificar se o código que está solicitando seu
# trabalho é incompatível. Restrições de versão serão impostas. 
DIR_LIBS="/TESTES/LIBS"

# local físico onte estarão os Scripts especializados das tarefas.
# Se nova versão no servidor remoto, atualização será automática.
# Este é o local REAL onde os Scripts estarão.
# Dependem da variável DIR_SCRIPTS e não de DIR_BASE, faz grande diferença.
# Neste momento, Scripts deverão estar ao alcance do usuário.
# Só um facilitador para os testes. Serão movidos a outro local furamente.
DIR_APLICATIVO="${_HOME}${DIR_SCRIPTS}"

# Diretório de bibliotecas de código reaproveitável.
# Se nova versão no servidor remoto, atualização será automática.
DIR_BIBLIOTECAS="${_HOME}${DIR_LIBS}"

# Caixa de entrada da máquina que solicita contador. Local RELATIVO.
# Se não existe, será criada.
# Na versão final, a caixa de entrada tem um arquivo de assinatura.
# Dentro do arquivo, várias linhas contendo as assinaturas e os serviços.
# Outro Script rodando em Cron na máquina, varre a caixa de entrada em
# busca de serviços a realizar.
CONF_ENTRADA="/CAIXA_DE_ENTRADA"

# Diretório físico da caixa posta de entrada.
DIR_CX_ENTRADA="${_HOME}${DIR_BASE}${CONF_ENTRADA}"

# Caixa de saida contém os serviços realizados. Local RELATIVO.
# O Script envia o conteúdo da caixa de saída para a caixa de entrada virtual.
CONF_SAIDA="/CAIXA_DE_SAIDA"

#Diretório físico da caixa de saída local.
DIR_CX_SAIDA="${_HOME}${DIR_BASE}${CONF_SAIDA}"

# Local RELATIVO para alocação das caixas de comunicação.
DIR_BASE_SERVER="/VIRTUAL"

# Local base onde irãO ficar os Scripts personalizados.
# Este diretório não será criado pelos Scripts locais.
# Só está sendo mencionado por questões de entendimento.
DIR_SCRIPTS_SERVER="/IGNORADO/SCRIPTS"

# Local onde ficarão todas as bibliotecas reaproveitáveis de código.
# Vide dica do DIR_SCRIPTS_SERVER.
DIR_LIBS_SERVER="/IGNORADO/LIBS"

# Caixas de entrada virtual. Opera em servidor remoto.
# Para realizar os testes, será criada caso não exista.
# Vai receber os arquivos de testes das várias máquinas. 
# Rotinas em cron irão pegar o conteúdo dos arquivos e assinaturas.
# Processarão as informações e enviarão retornos as caixas de saída.
DIR_CX_ENTRADA_REMOTA="${_HOME}${DIR_BASE_SERVER}/CAIXA_DE_ENTRADA"

# Caixa de saída irão conter as assinaturas e serviços realizados.
# Coleta será feita por quem solicitou e irá a caixa de entrada local.
# Nas sub-pastas também ficarão as novas versões dos Scripts.
# Se encontrar novas versões, as máquinas irão baixar estes arquivos
# Conforme as orientações contidas nos arquivos de serviço.
DIR_CX_SAIDA_SERVER=${_HOME}${DIR_BASE_SERVER}"/CAIXA_DE_SAIDA"

# Irá conter todos os 53 contadores de serviços.
# Irá armazenar alguns logs das máquinas solicitantes e retornos. 
# Arquivos de travas estarão em suas sub-pastas.
# Comanda a demanda de trabalho das estações automatizadas. 
DIR_TAREFAS=${_HOME}${DIR_BASE_SERVER}"/CONTADORES"

}

_config.pastas

return
 

------------------------------------------------------------------------------
Changelog temporário e as vezes quase definitivo.
------------------------------------------------------------------------------
2011-08-07 GA - Criado grande parte dos configs de pastas.
[CHANGED] Transferido algumas configs para este novo arquivo.
------------------------------------------------------------------------------
2011-08-07 GA_Tux - + testando se $_HOME está carregada e se existe dir.
+ Variável para controle de diretório RAIZ de arquivos temporários.
[CHANGED] Trocado nome de função para _config.pastas
------------------------------------------------------------------------------
Pendências:

Como criar man pages para Shell Script ??? Tem jeito ?
Onde obter um padrão de documentação para criar um help e manual completo ?
Como pegar e tratar todas as variáveis dinâmicamente só deste arquivo?
Tô bem de pendengas rsrs.
------------------------------------------------------------------------------

============ final de arquivo ================================================

Desculpe qualquer erro de escrita, nem revisei ainda.

A ideia é tentar deixar o mais portável possível para alterações nas configs.
Tem alguns locais ainda engessados, mas vou tentar melhorar.

Estou optando por não colocar o (_) no início destas que serão variáveis
globais. Claro que posso mudar de pensamento se algum padrão for mostrado.

Estou deixando as variáveis GLOBAIS com sublinhado quando são capturadas
do ambiente. [riscado]Será o próximo arquivo que deverei enviar.[/riscado]


exemplo: _HOME=$HOME , _USERNAME=$USERNAME e assim por diante.

É claro que se quiser padronizar todas vou mesmo precisar colocar o
(_) no prefixo da variável para poder fazer algum processamento geral
em cima das variáveis que estão no escopo do aplicativo.

Sugestões ?

GA_Tux