Full snippets of commented codes. Why?

Question

I’m learning PHP and use scripts ready to study them, as a complement.

However what I often see is whole snippets of commented code. Does anyone know why? Does it have any function?

If the project is ready and will not be used that part why not delete?

Answer 1

It’s right in your perception.

This is called commented out code. It is an excerpt that is in trouble, something that was being tested but not finished, it is an alternative form of that code that is not in use, it is something that needs to be polished and it is better not to leave in the application, it is old thing that should be erased.

While you are testing on your computer, doing this is a way that facilitates code debugging, or go incrementally into development, is to experiment, etc. So it’s a good thing.

When someone publishes the code that way, they’re doing it. Ideally, code like this should never be published. It should never go into code production this way, although it probably won’t affect the application directly. It’s a matter of organization.

Many programmers don’t know how to program, they do it and they don’t even know it’s bad. Some may do it consciously and don’t see a problem. Those who have experience and work alone can know what they are doing, although even in these cases it is common for them to forget about it, start accumulating, lose control of so much code left behind and they don’t even remember why it was like this.

Being obliged does not change the fact of being a gambiarra. Having a deadline to deliver does not serve as an excuse since it takes seconds to resolve. And reinforcement to apology since there is no productivity gain in the short run on doing so. In general there is loss in the long run.

A lot of times a person does this because they don’t have version control of their code, then they move something and they don’t want it to go away, so they leave the code there as a comment for future reference. But in fact it should erase even and let version control take care of it.

In short, there is this because one does not know well what they are doing and/or is sloppy.

Some people think it’s better to do the same in a way other than comment, but the effect is the same. When language leaves, some people do:

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

I put in the Github for future reference.

Some people like to make it easy to find these codes and create their own place to post deleted code, but don’t leave it in the original code.

Note that I am not talking about valid comments that help explain some situation of the code.

Answer 2

In addition to what has already been covered in the existing answer, there are also those code snippets that serve as an example of how to use a certain function.

Example:

/*
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.

}

This is also a very old habit from the time when "nobody" documented anything. Everything was documented in the code itself.

The ideal is to do everything organized with documentation on how to use routines and what they serve. As for removed codes it is recommended to have a versioning control.

There are still people who refuse to organize in this way and insist on "documenting" the code itself claiming that it is more practical. They don’t normally use versioning either. When you change something, you save a backup and arrange it manually. The problem is it’s out of order. When you need to work in teams, hire someone new, etc, you need to train that person to fit that unknown pattern globally.

A major problem in "documenting the code itself" is that it is very common for even the original code creator himself to not remember more than he did and remake something that already exists. Creates a new function and there is already a function that does what you want. But since there’s no documentation and it’s all inside a jumble of code out of tens of thousands of files, the guy will never remember because he doesn’t even have a tool that organizes the documentation. It has everything well described but inside comments in the archives.

The ideal is to organize using widely accepted standards.

Analogy

For those who are floating, let’s make an analogy. Think of an engineer with responsibility to build a skyscraper. The guy does not document using the engineering standard and decides to document writing on the walls of the building the way he thinks best. The building may not fall, but it will be a terror for maintenance. The building will last 100, 200, 400 years. Other engineers will continue maintenance and need documentation. But they will have to read the "comments" engraved on the floor, ceiling, pipes, walls, etc. And no guarantee that they are understanding correctly.

PHP Documentation

It is important not to confuse it with those commented codes under a certain pattern. If you see something like this it is some standard documentation:

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

phpDocumentator, Doxygen, among others.

See more on SO-en: https://stackoverflow.com/questions/1182781/how-do-you-document-your-php-functions-and-classes-inline

The example here is about PHP due to the tag you put in the question, but the logic is the same for any project even outside the computer area.

Not everything is perfect

Of course, having versioning and organized documentation does not mean anything if it is poorly described. It is also common to pick up projects where versions do not have clear descriptions. They are usually vague things that make it more confusing. And in the documentation also vague things, no examples of use, no explanations of relevant details.

Example 1, negligence:

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

They usually ignore small codes and don’t detail what it’s for. It records in the documentation but doesn’t explain what this crazy business does. Sometimes it’s even garbage you forgot to remove but you just sit around.

Example 2, sloppiness:

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

Go to the documentation and find a generic description:

"This function is responsible for bringing the result of the request and returns an array"

So you’re like, "Yeah, so what? How do you use that shit*?".

Even worse when you read the versioning, in the descriptions, in practically everything is like this: "Added improvements".
This way is even worse than doing "the old way" describing in the code itself in comment form.

What is right is to be very clear and descriptive.

Ethics

An observance that few care about is not misjudging someone else’s work because you don’t know the conditions, causes, reasons, reasons and circumstances that the previous programmer had to do X or Y.

For example, often the programmer is forced to do something he does not want to do and must obey because he is a subordinate. Another situation is the rush to do something urgent. The boss demands that the guy complete a drastic change in the system within an unfeasible timeframe where he won’t even have time to test, let alone document. So you stick it all in the codes anyway and leave it to me to sort it out when you get a chance. Of course the day to organize never comes and it stays there even clutching with other situations also urgent.

Therefore, when you take a project that another professional left, avoid speaking badly because you may be harming the person unfairly. The criticism you leave for later when you understand what and why it was that messed up way. And sometimes when you criticize without knowing the reasons, you end up burning yourself. Do not misjudge because not all programmers have the privilege to be able to work in a fully organized environment.