Is it recommended to explain all variables?

Question

This is a question as to the readability of the code or if there is any style pattern as to this.

Well, the Zen of Python tells us that

Explicit is Better than implicit.

but how to interpret this?

Think about the following approaches:

Approach 1:

class TicketInfos:
    ...
    ...

    def create_sheet(self):
        client_name = self._get_client_name()
        wb = Workbook(f'Tickets - {client_name}.xlsx')
        ...
        ...

Approach 2:

class TicketInfos:
    ...
    ...

    def create_sheet(self):
        wb = Workbook(f'Tickets - {self._get_client_name()}.xlsx')
        ...
        ...

It is recommended that I follow the first approach, explaining the variable client_name? I particularly prefer to follow the second approach since the function name _get_client_name() is very self-explanatory.

However, I always try to explain a variable if I’m going to use it to call another function. I mean, I prefer to do:

class _CustomValues:
    ...
    ...

    def get_impact_value(self):         
        def _get_impact_value(classification):
                ...
                ...

        impact_classification = self._get_custom_item(self.impact_id)
        return _get_impact_value(impact_classification)

instead of

class _CustomValues:
    ...
    ...

    def get_impact_value(self):         
        def _get_impact_value(classification):
                ...
                ...

        return _get_impact_value(self._get_custom_item(self.impact_id)) 

What is recommended?

Answer 1

Broad rules, ambiguous and vague, help to think about the subject, but do not serve as something definitive of what should be done. This rule does not say what should be explicit. The rule is broken all the time in many points of the language, in some no, of course. It is not always easy to find the point of balance of what should be explicit or not. If it is all or nothing gets complicated.

I remember once a teacher asked for a job to make a code where all functions were broken into the simplest possible operation, I questioned. I delivered on purpose a code that was practically an Assembly, each function only made a single operation as simple as possible, never two or more. So outside of doing something dirty, the right thing is to look at the context, gain experience, think about it and decide case by case.

If you take the rule to the last consequences you have to do what I just described with variables, each simple operation must be stored in a variable, will you do this? I think it’s silly.

One variable should be used primarily: a) to store a data temporarily to be used later; b) because it needs it longer or because it will be used more than once. Nothing prevents using the variable for other things, including a recommendation to use a variable to better document what you are doing and so avoid a comment saying what you are doing or leaving with nothing and it is not clear what this is. That’s what you’re talking about, but it’s secondary use of the variable.

In the example what did this variable add? For me nothing. It essentially reproduces the name of the method you are calling, does not document anything. What good does that do? Everything you do in the code by putting or taking out needs to have an advantage, even if it’s not functionality, you need to know how to justify why you did it, you can’t do it by doing it, or because someone said you should do it, that someone is not writing his code and it will not be that person who will suffer the pains.

You’re on the right track. Some people may disagree, but I lose respect for who does it :P Remembering that I’m talking about this case.

The second case presented in the question is already more complicated and would need to better understand the context. There already generates more controversy because the variable generates new information and can be useful to make more readable. I do not know if it is so necessary.

Python is a language of script then you have two things to think about, first that scripts shouldn’t be this complicated, so it shouldn’t be so necessary. On the other hand, it should be script performance doesn’t matter, so creating a random variable won’t hurt much. In many languages create a variable until some of the code, but not in Python and the creation of a variable has a higher cost than most languages (no script).

I look good on the wall there and I think saying go here or there falls a lot in opinion. I would use a different pattern depending on the language or type of the project. In Python I would not create the variable, but I would only use Python for very simple things and not for complex things as many people do, for me it would be the wrong tool.

If you’re a team follow what the team tells you, if you define what to do create a pattern and follow it (create less vague rules).