SSCCE: Uma necessidade pouco conhecida - O SSCCE (Short, Self Contained, Correct and Compilable Example)
Escrito por Carlos B. Feitoza Filho | |
Categoria: Artigos | |
Categoria Pai: ZØST | |
Acessos: 15831 |
Páginas dentro deste artigo
O SSCCE (Short, Self Contained, Correct and Compilable Example)
Se você anda tendo problemas com algum código e está buscando ajuda, preparar um exemplo pequeno, sem dependências externas, correto e compilável (sigla em inglês: SSCCE) é muito útil. Mas em que consiste um SSCCE? Na verdade está tudo na sigla, veja cada parte dela e prepare o código para que outras pessoas possam te ajudar da seguinte maneira:
- Pequeno (Short), a fim de minimizar o tempo de download (no caso de um executável) e acelerar a leitura (no caso de código-fonte) e com isso não chatear as pessoas que querem te ajudar;
- Sem dependências externas (Self Contained), ou seja, garanta que tudo está incluído e pronto para começar a compilar e reproduzir o comportamento;
- Correto (Correct) e compilável (Compilable), por exemplo, copie e cole seu código e depois compile e execute para saber se ele reproduz o problema ou comportamento peculiar da mesma forma que acontece em seu local original;
A última letra da sigla (E), significa exemplo e não precisa de detalhamentos.
Pequeno (Short)
O tamanho do código é bem relativo e depende de onde você o está publicando, por exemplo, em um fórum público, pesquisas mostram que as pessoas vão parar de ler a partir da centésima linha de código e começarão a reclamar quando o código contiver de 250 a 300 linhas de código. Em um grupo de Facebook, todos estes números são significativamente menores devido às limitações da rede social, que não foi projetada para aceitar textos com códigos-fonte. A dica então é enxugar ao máximo o exemplo, mas como?
Dicas para deixar o exemplo mais enxuto
- Se a GUI tem 40 botões que não estão relacionados ao problema, remova-os. Se eles estiverem relacionados ao problema e ao removê-los o problema desaparece, mantenha apenas um ou dois botões com os quais o problema seja reproduzível;
- Se o problema reside em um array ou em uma tabela, eles podem ter centenas de itens e, novamente, se o problema pode ser visto com dois ou três desses itens, mantenha apenas a quantidade mínima de itens para que o problema seja reproduzível;
- Se o problema estiver relacionado apenas ao layout da GUI, remova todos os processamentos que estiverem sendo feitos por trás dessa GUI. Por outro lado, se o programa tem uma GUI mas o problema é o processamento que fica por trás dela, enxugue a GUI de forma que ela tenha apenas o número mínimo de controles com os quais seja possível reproduzir o problema de processamento;
- Ao tentar enxugar um código muito extenso tome cuidado para não exagerar e cortar também a parte que está apresentando problemas ou que influencie na parte que está apresentando problemas.
Problema resolvido?
Ao tentar identificar mais claramente onde o problema ocorre, você termina dando um importante passo na resolução deste problema. O processo que consiste em isolar onde o problema se origina pode por si só, ajudar a resolvê-lo, pois você olha mais de perto aquela parte isoladamente e, fazendo isso, o problema pode ficar bem mais à mostra. Mesmo que você não consiga identificar porque o problema ocorre, você ainda dá um importante passo: identificar, ao menos em parte, o código envolvido.
Se ao isolar parte do código você obtiver um exemplo conciso do problema, ele está pronto para ser apresentado como SSCCE aos outros, do contrário, continue isolando o código até que ele seja apresentável.
Sem dependências externas (Self Contained)
É muito importante garantir que o código apresentado a outras pessoas possa ser copiado, colado, compilado e executado, de forma que elas possam ajudar o mais rápido possível e com o mínimo de confusão. Isso significa que após o código ser copiado, colado e compilado pelas pessoas que estão dispostas a ajudar, elas poderão executar e ver os resultados elas mesmas, pois este é um exemplo do problema. Mantendo seu exemplo independente fará com que você receba ajuda muito mais rapidamente e de forma mais precisa.
Como fazer um exemplo sem dependência externas?
- Se o código executa I/O em arquivos, substitua o I/O por dados fictícios em problemas que não estão relacionados a input/output;
- Se o problema estiver relacionado a I/O e a entrada (arquivo) puder ser compartilhada, prepare uma pequena amostra do arquivo de dados e disponibilize juntamente com o seu SSCCE;
- Se o problema ocorre apenas ao carregar, insira código para simular esta carga;
- Se um problema de layout ocorre apenas sob circunstâncias particulares, force essa circunstância a acontecer sempre que for possível.
Obviamente existem coisas que não podem ser incluídas em um exemplo que é publicado em um fórum ou rede social (um banco de dados, por exemplo) mas muitas vezes você precisa apenas pensar fora da caixinha a fim de substituir aquilo que você considera vital para demonstrar o seu problema. Um exemplo de pensamento não convencional está relacionado a imagens. Imagens associadas a problemas de codificação podem ser difíceis de substituir ou compartilhar juntamente com o SSCCE, mas uma dica seria linkar uma imagem disponível na própria web, uma com a qual seja possível reproduzir o mesmo problema. Tente fazer qualquer imagem pequena (tamanho de arquivo) sempre que for possível.
Correto e compilável (Correct / Compilable)
Se meu exemplo está correto, o que eu estou fazendo aqui?!
(Risos histéricos) Não! Não é disso que se trata quando falamos "correto" neste contexto. Em um SSCCE, "correto" (e compilável), significa garantir que o exemplo obedeça certos padrões e protocolos. Para alcançar isso é necessário que:
- A largura máxima das linhas de código esteja por volta de 62 caracteres, incluindo as endentações e o motivo desta necessidade é que os programas leitores de notícias (newsreaders) tipicamente forçam uma quebra de linha por volta de 72 caracteres e é melhor ficar bem abaixo deste limite. Ao publicar texto em redes sociais verifique o tamanho máximo de cada linha e faça o possível para não exceder o limite de caracteres, fixando cada linha em um número adequado de caracteres. Esse item parece exagero, mas não é. Algumas vezes as quebras de linha não causam qualquer problema, mas usualmente elas causam, pois precisam se tornar linhas contíguas novamente antes de funcionarem como devem. A maioria dos editores de código mostram a quantidade de caracteres em cada linha e muitos deles mostram uma linha do lado direito, indicando a coluna de quebra. Use esta linha para se orientar;
- O código use convenções de nomenclatura caso isso seja requerido pelo público-alvo de seu SSCCE. A maioria das pessoas dispostas a ajudar ficará mais confortável em fazê-lo ao ver um código bem feito, que segue normas e usa nomes descritivos para os identificadores. Esses cuidados simples ajudarão a detectar mais rapidamente o problema. Em suma, ao seguir as convenções a que o público está acostumado, a ajuda certamente será mais rápida;
- Garantir que o exemplo compile de forma limpa e que ele cause o comportamento (ou erro) exato para o qual se quer a solução;
- Mova todos os recursos necessários para o mesmo diretório de forma que ele sejam facilmente encontrados e administrados. Isso inclui arquivos de fonte, imagens, arquivos de dados, dentre outros.
Terminou o exemplo?
Você trabalhou no exemplo por horas, talvez dias que pareceram durar para sempre. Agora é um bom momento para recuperar o fôlego, espreguiçar-se e relaxar. Talvez sair para dar um passeio. Dê um descanso ao computador também, reinicie-o ou mesmo desligue-o por algumas horas.
Após ter relaxado o suficiente, volte ao computador, abra o SSCCE e verifique se o problema ainda ocorre. Em 99% das vezes o erro ainda persistirá e você pode publicar o exemplo. Caso o erro não reproduza mais, ele entrará naquele rol de coisas sobrenaturais que acontecem nos computadores e você tem duas opções: relaxar de novo e pagar alguma promessa feita ou ficar tentando desesperadamente fazer o erro acontecer de novamente. A minha experiência mostra que a segunda opção é sempre a pior. Se estiver funcionando e você não conseguir reproduzir o erro de forma alguma, é melhor assumir que houve algum problema no sistema operacional e manter o exemplo, para o caso do erro acontecer novamente.