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.
/* funcao($parametro) { return $parametro; } */