15

Estou aprendendo PHP e uso scripts prontos para poder estudá-los, como forma de complemento.

No entanto o que costumo ver com frequência é trechos inteiros de códigos comentados. Alguém sabe o porquê? Tem alguma função?

Se o projeto está pronto e não será utilizado aquela parte porque não apagar?

4
  • "Estou aprendendo PHP e uso scripts prontos para poder estuda-los...", não os percebes melhor estando comentados? Não te ajuda ter uma explicação sobre o que faz um determinado bloco? É por isso
    – Miguel
    Commented 25/01/2017 às 14:47
  • @Miguel Acho que ele quis dizer que tem blocos de código dentro dos comentários. Algo como: /* funcao($parametro) { return $parametro; } */
    – Jéf Bueno
    Commented 25/01/2017 às 14:52
  • haa @jbueno, percebido, sendo assim a pergunta acabou de ficar melhor
    – Miguel
    Commented 25/01/2017 às 14:53
  • @jbueno Exatamente.
    – Marcos
    Commented 25/01/2017 às 14:53

2 Respostas 2

20

Está correto na sua percepção.

Isso é chamado de commented out code. É um trecho que está com problemas, algo que estava sendo testado mas não terminou, é uma forma alternativa daquele código que não está em uso, é algo que precisa dar uma polida e é melhor não deixar na aplicação, é coisa antiga que deveria ser apagada.

Enquanto você está testando em seu computador, fazer isso é uma forma que facilita a depuração de códigos, ou ir incrementalmente no desenvolvimento, é para experimentar, etc. Então é algo bom.

Quando alguém publica o código dessa forma está fazendo gambiarra. Idealmente nunca deveria ser publicado código assim. Nunca deveria ir pra produção código dessa forma, apesar de que provavelmente não afetará a aplicação de forma direta. É uma questão de organização.

Muito programador não sabe programar, faz isso e nem sabe que é ruim. Alguns talvez o façam conscientemente e não veem problema. Quem tem experiência e trabalha sozinho pode saber o que está fazendo, ainda que mesmo nesses casos é comum ele esquecer daquilo, começar acumular, perder controle de tanto código deixado pra trás e ele nem lembrar porque estava assim.

Ser obrigado não muda o fato de ser gambiarra. Ter prazo para entregar não serve de desculpa já que isso leva segundos para resolver. E reforço a desculpa já que não há nenhum ganho de produtividade no curto prazo em fazer assim. Em geral há perda no longo prazo.

Muitas vezes a pessoa faz isso porque não tem controle de versão de seus códigos, aí ele mexe em algo e não quer que aquilo suma, então ele deixa o código lá como comentário para referência futura. Mas na verdade ele deveria apagar mesmo e deixar o controle de versão cuidar disso.

Em resumo, tem isso porque a pessoa não sabe bem o que está fazendo e/ou é desleixada.

Algumas pessoas acham melhor fazer o mesmo de outra forma que não o comentário, mas o efeito é o mesmo. Quando a linguagem deixa, há quem faça:

#if 0
    todo código a ser "desligado" aqui
#endif

Coloquei no GitHub para referência futura.

Há quem goste de facilitar achar esses códigos e criam um local próprio para postar código deletado, mas não deixa no código original.

Note que não estou falando de comentários válidos que ajudam explicar alguma situação do código.

1
  • 2
    Eu costumo fazer no ambiente de desenvolvimento, nunca no "release" (esse vai limpo), justamente pelo motivo que citou e também quando estou testando algo novo, mas o antigo ainda "funciona", então comento o antigo, mas não fica muito tempo e geralmente eu nem faço commit local. +1
    – Syzoth
    Commented 25/01/2017 às 15:11
12

Além do que já foi abordado na resposta existente, existe também aqueles trechos de código que servem como exemplo de como usar uma determinada função.

Exemplo:

/*
Usage sample 1:

$rs = Foo(123);

return array(1, 2, 3);

Usage sample 2:

$c = Bar::Method('any');
$rs = Foo(123, $c);

return array(1, 2, 3, 'Bar' => (stdclass))
*/

function foo($arg1, $arg2 = null, $arg3 = null, $arg4 = null)
{

    // aqui tem as rotinas, as firulinhas, etc.

}

Isso é também um hábito muito antigo do tempo em que "ninguém" documentava nada. Tudo era documentado no próprio código.

O ideal é fazer tudo organizado com uma documentação sobre como usar as rotinas e para que servem. Quanto a códigos removidos é recomendado ter um controle de versionamento.

Ainda há pessoas que recusam organizar dessa forma e insistem em "documentar" no próprio código alegando que é mais prático. Normalmente também não usam versionamento. Quando vai mudar algo, salva um backup e organiza a seu modo manualmente. O problema é que fica despadronizado. Quando precisa trabalhar em equipes, contrata alguém novo, etc, é necessário treinar essa pessoa para que se adeque a esse padrão desconhecido globalmente.

Um problema grande em "documentar no próprio código" é que é muito comum até mesmo o próprio criador do código original nem lembrar mais do que fez e refaz algo que já existe. Cria uma função nova sendo que já existe uma função que faz aquilo que deseja. Mas como não há uma documentação e está tudo dentro de um emaranhado de códigos dentre dezenas de milhares de arquivos, o cara nunca vai lembrar pois não tem sequer uma ferramenta que organiza a documentação. Ele tem tudo bem descrito porém dentro de comentários nos arquivos.

O ideal é organizar usando padrões amplamente aceitos.

Analogia

Para quem está boiando, vamos fazer uma analogia. Pense num engenheiro com responsabilidade de construir um arranha céu. O cara não documenta usando o padrão da engenharia e resolve documentar anotando nas paredes do edifício do jeito que acha melhor. O edifício pode não cair, mas será um terror para a manutenção. O edifício vai durar 100, 200, 400 anos. Outros engenheiros darão continuidade na manutenção e precisam de uma documentação. Mas terão que ler os "comentários" gravados no chão, no teto, nas tubulações, paredes, etc. E sem garantia de que estão entendendo corretamente.

PHP Documentation

É importante não confundir com aqueles códigos comentados sob um determinado padrão. Se você ver algo assim é algum padrão de documentação:

/**
* This is the description for the class below.
*
* @package    my-package
* @subpackage my-subpackage
* @author     my-name
* @version    my-version
* ...
*/

phpDocumentator, Doxygen, dentre outros.

Veja mais no SO-en: https://stackoverflow.com/questions/1182781/how-do-you-document-your-php-functions-and-classes-inline

O exemplo aqui é sobre PHP devido a tag que colocaste na pergunta, mas a lógica é a mesma para qualquer projeto mesmo fora da área de informática.

Nem tudo é perfeito

Claro que possuir versionamento e documentação organizada não quer dizer nada se estiver mal descrito. É comum também pegar projetos onde os versionamentos não possuem descrições claras. São normalmente coisas vagas que tornam mais confuso. E na documentação também coisas vagas, sem exemplos de uso, sem explicações de detalhes relevantes.

Exemplo 1, negligência:

function foo()
{
    // um codigo pequeno de 2 linhas
}

Normalmente ignoram códigos pequenos e não detalham para que serve. Registra na documentação mas não explica o que esse negócio doido faz. As vezes é até lixo que esqueceu de remover mas fica aí a toa.

Exemplo 2, desleixo:

function foo()
{
    // um codigo imenso cheio de coisas sinistras e obscuras
}

Você vai na documentação e encontra uma descrição genérica:

"Essa função é responsável por trazer o resultado da requisição e retorna um array"

Então você fica pensando: "tá, e daí? como que usa essa porr*?".

Pior ainda quando lê o versionamento, nas descrições, em praticamente tudo está assim: "Foi adicionado melhorias".
Dessa forma fica até pior que fazer "da forma antiga" descrevendo no próprio código em forma de comentário.

O certo é ser bem claro e descritivo.

Ética

Uma observância que poucos se importam é não julgar equivocadamente o trabalho alheio pois você não sabe das condições, causas, motivos, razões e circunstâncias que o programador anterior teve para fazer X ou Y.

Exemplo, muitas vezes o programador é forçado a fazer algo que não quer e deve obedecer por ser um subordinado. Outra situação é a pressa em fazer algo urgente. O patrão exige que o cara termine uma mudança drástica no sistema num prazo inviável onde não terá tempo nem mesmo para testar, quanto menos para documentar. Então vai enfiando tudo de qualquer jeito nos códigos e deixa para organizar quando tiver tempo. Lógico que o dia para organizar nunca vem e aquilo vai ficando ali mesmo embolando com outras situações também urgentes.

Por isso, quando você pega um projeto que outro profissional deixou, evite ficar falando mal pois pode estar prejudicando a pessoa de forma injusta. As críticas você deixa para depois quando compreender o que e por que aquilo estava daquele jeito bagunçado. E as vezes quem critica sem saber as razões é que acaba se queimando. Não julgue de forma equivocada pois nem todos os programadores tem o privilégio em poder trabalhar num ambiente totalmente organizado.

Você deve fazer log-in para responder a esta pergunta.

Esta não é a resposta que você está procurando? Pesquise outras perguntas com a tag .