SSCCE: Uma necessidade pouco conhecida
| Escrito por Carlos B. Feitoza Filho | |
| Categoria: Artigos | |
| Categoria Pai: ZØST | |
| Acessos: 15030 |
Introdução
A definição abaixo é um resumo e serve para que você já saiba desde o início do que se trata o SSCCE. Se você chegou aqui porque não sabia o que é um SSCCE e lhe foi fornecido este link, você poderá voltar ao fórum, grupo ou lista de discussão original e continuar a buscar o que precisa, fornecendo um SSCCE. Se você quiser saber mais, continue lendo clicando no link para a próxima página, a qual contém a versão brasileira resumida do texto original disponível em http://sscce.org. Este texto contém a definição mais detalhada do SSCCE, bem como dicas de como construir um bom SSCCE. Também tomei a liberdade de incluir algumas informações adicionais que eu julguei necessárias a fim de tornar o texto mais condizente com a nossa realidade, que possui redes sociais como forma de troca de informações.
Um SSCCE, é o menor exemplo de código compilável sem dependências externas, com o qual é possível expor corretamente um problema ou comportamento de um programa, abstraindo partes do mesmo que não interessam e que potencialmente poderiam atrapalhar no entendimento de tal problema
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.
Por que eu devo me importar com isso tudo?
Essa é uma ótima questão. Para que todo esse esforço? Talvez algumas pessoas consigam entender o problema que você descreve apenas lendo o que você escreveu. Talvez sua dúvida seja uma daquelas que milhares de pessoas já tiveram anteriormente e conseguiram resolver. Se você já checou todos os FAQs disponíveis, se já pesquisou exaustivamente no Google (ou dentro do próprio recurso no qual você pretende publicar o seu SSCCE), se já leu a ajuda online da ferramenta que utiliza (o Delphi tem uma muito boa, sabia?) é provável que uma resposta surja facilmente. Você fez isso tudo, não fez??!!
Se você não buscou sozinho a solução de todas as formas que lhe são acessíveis (e normalmente são muitas hoje em dia), você estará apenas desperdiçando o tempo e a largura de banda dos outros membros de um fórum, lista de discussão ou grupo de Facebook. Dessa forma você se arrisca a receber respostas vazias, mal humoradas, piadas de mal gosto e outras pérolas
As pessoas que contribuem ajudando outras pessoas dão uma ampla gama de conselhos. Às vezes, o conselho funciona, às vezes não, mas de qualquer forma, o conselho sempre é gratuito. Os contribuintes fazem isso por uma variedade de razões, incluindo a sensação de dever cumprido quando se consegue transmitir um conhecimento para alguém que está aprendendo. Infelizmente quando alguém pede informações mastigadas que poderiam ser encontradas em qualquer tutorial básico, esta é uma forte indicação de que o questionador não quer aprender e sim fazer com que os outros façam o trabalho que ele deveria fazer.
Se houver um código e você deseja que ele seja escrito, finalizado ou resolvido por outros, há muitas formas de conseguir isso. Por uma quantidade modesta de dinheiro, você pode obter a maior parte do trabalho de TI complementado (ou concluído) através de uma série de empresas terceirizadas baseadas na internet. Pense a respeito! A grande maioria dos fóruns, listas de discussão e grupos de Facebook são locais de aprendizado.
Dito isso, suponhamos que você realmente "não se importe em aprender". Digamos que você tenha um sistema enorme e complexo com um bug ocasional e imprevisível, e que você pesquisou todos os recursos que estavam ao seu alcance e que não tenha conseguido achar uma resposta satisfatória. Neste caso sinta-se à vontade para descrever o problema para as pessoas. Talvez seja um mal-entendido básico da sua parte que pode ser facilmente esclarecido.
Não estamos propondo que todos os problemas precisem de um SSCCE para serem resolvidos. Também não sugerimos que um exemplo seja, ou deva ser, obrigatório. Mas é fato que o desenvolvimento de um exemplo simples tornará as pessoas muito mais propensas a ajudar e, portanto, aumentará a chance de encontrar uma solução.