Digression on short variable names

[DNF]

@Wooheon

The followings are MatLab code and Julia code each.

%First, set up given data%
alpha=0.261;beta=0.99;delta=0.0176;n_star=1;
z_grid=[0.9526;0.9760;1;1.0246;1.0497];
Pi_z=[0.9149 0.0823 0.0028 0 0;...
    0.0206 0.9163 0.0618 0.0014 0;...
    0.0005 0.0412 0.9167 0.0412 0.0005;...
    0 0.0014 0.0618 0.9163 0.0206;...
    0 0 0.0028 0.0823 0.9149];
%Next, get the k_star and k_L and k_H%
k_star=(1/alpha*(1/beta-1+delta))^(1/(alpha-1));
k_L=k_star*0.85;k_H=1.15*k_star;
disp(round(k_star,4));disp(round(k_L,4));disp(round(k_H,4));
%Setting up an 499 points of kgrid%
k_grid=(k_L:((k_H-k_L)/498):k_H).';
disp(median(k_grid));

%%(b)%%
%First, set up the length variables%
n_k=length(k_grid);n_z=length(z_grid);
%Now initialize a V array%
V=zeros(n_k,n_z);
%Make settings for the iteration%
%First, make an array for each z_i%
k_prime_grid_mat_proto=repmat(k_grid,[1 n_z n_k]);%build prototype k' array with 3-d block array%
k_grid_mat=permute(k_prime_grid_mat_proto,[3 2 1]);%build k array with 3-d block array%;
k_prime_grid_mat=k_prime_grid_mat_proto.*(k_grid_mat.^alpha.*z_grid.'+k_grid_mat.*(1-delta)-k_prime_grid_mat_proto>=0);
k_prime_grid_mat(k_prime_grid_mat==0)=nan;
logC=log(k_grid_mat.^alpha.*z_grid.'+k_grid_mat.*(1-delta)-k_prime_grid_mat);
%build k' array that assigns nan to k' that is out of bound%

precision=0.01;distance=100;sz=size(k_prime_grid_mat);%precision and initial distance%

i=1;%iteration number%

%Start iteration%
while (distance > precision)
    [TV,Tk_index]=max(logC+repmat(V*Pi_z.',[1 1 n_k]).*beta,[],'omitnan');%max within column omitting nan%
    TV=reshape(permute(TV,[1,3,2]),[],size(TV,2));%change 1x5x499 array into 499x5 matrix%
    distance=max(max(TV-V));
    i=i+1;disp(i);disp(distance);
    if distance<precision
        break
    else
    V=TV;k_index=Tk_index;
    end
end

%reviving k-rules from the k_index array%
k_prime_sol=k_prime_grid_mat_proto(Tk_index);
k_prime_sol_mat=reshape(permute(k_prime_sol,[1,3,2]),[],size(k_prime_sol,2));%change array into matrix%
k_prime_sol_previous=k_prime_grid_mat_proto(k_index);
k_prime_sol_previous_mat=reshape(permute(k_prime_sol,[1,3,2]),[],size(k_prime_sol_previous,2));%change array into matrix%
%matrix of previous capital to compare with solutions%
distance_k=max(max(abs(k_prime_sol_mat-k_prime_sol_previous_mat)));

%answers%
disp(i);disp(distance);disp(distance_k);

using Statistics
##(a)##
#First, set up the given data#
const alpha=0.261;const beta=0.99;const delta=0.0176;const n_star=1;
const z_grid=[0.9526;0.9760;1;1.0246;1.0497];
const Pi_z=[0.9149 0.0823 0.0028 0 0;
    0.0206 0.9163 0.0618 0.0014 0;
    0.0005 0.0412 0.9167 0.0412 0.0005;
    0 0.0014 0.0618 0.9163 0.0206;
    0 0 0.0028 0.0823 0.9149];
#Next, get the k_star and k_L and k_H#
const k_star=(1/alpha*(1/beta-1+delta))^(1/(alpha-1));
const k_L=k_star*0.85;const k_H=1.15*k_star;
println(round(k_star,digits=4));println(round(k_L,digits=4));println(round(k_H,digits=4));
#Setting up an 499 points of kgrid#
const k_grid=[k_L:((k_H-k_L)/498):k_H;];
println(median(k_grid))

##(b)##
#First, set up the length variables#
const n_k=length(k_grid);const n_z=length(z_grid);
#Make settings for the iteration#
#First, make an array for each z_i#
const k_prime_grid_mat_proto=repeat(k_grid,1, n_z, n_k);
const k_grid_mat=permutedims(k_prime_grid_mat_proto,(3,2,1));
k_prime_grid_mat=k_prime_grid_mat_proto.*(k_grid_mat.^alpha.*transpose(z_grid)+k_grid_mat.*(1-delta)-k_prime_grid_mat_proto.>0);
k_prime_grid_mat[k_prime_grid_mat.==0].=NaN;#build k' array that is out of bound#
logC=log.(k_grid_mat.^alpha.*transpose(z_grid)+k_grid_mat.*(1-delta)-k_prime_grid_mat);
logC[isnan.(logC)].=-Inf;
    
const precision=0.01;
const startdistance=100;#precision and initial distance#
#iteration number#

#start iteration#
function loop_over_global(distance, precision)
    #Now initialize a V array#
    global V=zeros(n_k,n_z);global i=1;
    while distance>precision
        global (TV,Tk_index)=findmax(logC::Array{Float64, 3}+repeat(V*transpose(Pi_z),1, 1, n_k).*beta,dims=1);
        global TV=transpose(reshape(TV,5,499));
        distance=maximum(TV-V);
        println(i);println(distance);
        if distance≤precision
            break
        else
            global V=TV; global k_index=Tk_index; i=i+1;
        end
    end
    return (TV,V,Tk_index,k_index,distance);
end

global (TV,V,Tk_index,k_index,distance)=loop_over_global(startdistance,precision);
#Reviving k-rules from the k_index array#
k_prime_sol_mat=transpose(reshape(k_prime_grid_mat_proto[Tk_index],5,499));
k_prime_sol_mat_previous=transpose(reshape(k_prime_grid_mat_proto[k_index],5,499));#matrix of previous capital to compare with solutions#
distance_k_prime_sol=maximum(abs.(k_prime_sol_mat-k_prime_sol_mat_previous));

##for information; how to convert a cartesian index array into matrix with only necessary info(first entry of the cartesian index)##
Tk_index=first.(Tuple.(Tk_index));Tk_index=transpose(reshape(Tk_index,5,499));
    
#answers#
println(i);println(distance);println(distance_k_prime_sol);

Thanks for reading this cumbersome codes. I wish I could get fluent in this fantastic language.

One gripe, perhaps my pet peeve: long variable names make code hard to read. It’s a wall of text with numerous very similar long names. And for a casual reader, the names carry no information. It’s just hard to follow the code.

This is why mathematics normallt use single-letter variable names.

Can you shorten the names for clarity?

[tfiers]

Absolutely agree.
I’m no fan of the current ‘wisdom’ in software engineering to use long explanatory variable names.
Totally obscures the ‘gestalt’ of the code.

Explanation should go in comments and docs.

[sylvaticus]

disagree

this code is a bit exagerated, there are no spaces, no formatting… but in general I prefer much more to have a hint in the var name of what a particular variable refers to in the specific application that is under study… pure math often do not need to have an application of a particular computation, so one letter var would be fine, but I don’t think it is the case in a general way… but this is really OT to the discussion… yes, try to remove all that junk of global variables and pass them as function srguments instead…

[DNF]

@sylvaticus

but in general I prefer much more to have a hint in the var name of what a particular variable refers to

[hijack]
This is where the word “concise” applies. Work hard to make the var names short and clear.

Too short names makes code inscrutable. Too long names makes code unreadable. It’s a tradeoff.
[/hijack sorry]

[tfiers]

@sylvaticus

in general I prefer much more to have a hint in the var name of what a particular variable refers to in the specific application that is under study

Yes I do agree; “only use single-letter variable names” is too strong. (Not that anyone said that).

But if you have sth like, e.g,

function run!(s::Simulation)
    while !completed(s)
        step!(s)
    end
    return s
end

why would you want to call the variable simulation.
sim is fine.

Indeed we’re going totally off-topic, maybe a mod could split off?

[cvanaret]

I totally agree. When it’s well done, complex codes with longer explanatory variable names are muuuuch easier to read than cryptic codes with math notations. Obviously this is personal preference, but I don’t want want to switch back and forth between the code and the paper/documentation to understand what’s happening. Yes, UTF-8 characters in Julia are awesome, but that’s not an excuse to clutter the code with Greek letters.

The variable is a stiffness matrix? Call it stiffness_matrix.
The variable is a list of violated constraints? Call it violated_constraints.
Reads like English.

It’s an art to figure out good names and it takes a lot of time to refine. I can only recommend Kate Gregory’s talks on the topic (e.g. “Naming is hard: let’s do better”).

Edit: why the hell would you want to call a “simulation” variable “sim”? Are we talking about a simulation or a sim card? With poor design, that’s the main reason why codes become unmaintainable. Ambiguity must be avoided.

[tfiers]

@cvanaret

why the hell would you want to call a “simulation” variable “sim”? Are we talking about a simulation or a sim card? Ambiguity must be avoided.

I agree in a vacuum, but the whole point of short variable names is that they make sense in context. Here, the semantic context is contained within the function.
The type (sim::Simulation, i.e. disambiguation) is right there.

Take a sorting algorithm eg.
Much easier to understand with long rather than short names (see julia src).
↓
EDIT: I meant to say “easier to understand with short rather than long names”

[cvanaret]

Yes, I must say it makes sense in your example because s::Simulation is never 3 lines away of the line you’re reading. But “real” functions are often longer and the frontier between “short is fine” and “short is terrible” is not that clear.
Also agree that we could fork topics

[tfiers]

@cvanaret

But “real” functions are often longer and the frontier between “short is fine” and “short is terrible” is not that clear.

Yes agree that the frontier is murky.

I have to note though that this is a real function (I copy-pasted it from the spiking-neural-network simulation library I’m writing, which is full of short functions).
Julia’s “structs-and-functions” design (without inheritance and mixins etc) makes short functions very common.

[DNF]

@cvanaret

But “real” functions are often longer

Functions should be short, just like names.

And it should be stiffness, not stiffness_matrix.

[CameronBieganek]

There is a rule of thumb here:

The shorter your function, the shorter your variable names can be.

Also, in Julia (as mentioned above) argument annotations can disambiguate short variable names. But of course you shouldn’t add argument annotations just to disambiguate a variable name—only use argument annotations for dispatch.

The other dimension here is library vs application code, with the rule of thumb being that application code requires longer variable names than library code.

[joa-quim]

@cvanaret

Yes, UTF-8 characters in Julia are awesome, but that’s not an excuse to clutter the code with Greek letters.

[joa-quim]

@CameronBieganek

There is a rule of thumb here:

The shorter your function, the shorter your variable names can be.

I loved this one.

As a rule to myself, I always try to make functions not taller than a laptop screen height. Then I feel free to use very short-up-to-one-single-char variable names because I can read all function without up-down scrolling. When that is not possible, I try that in the day after I still can tell what a variable name stands for just by reading its name.

[John_Gibson]

I for one am so happy to have, for example, λ rather than lambda as a variable for eigenvalues, ŷ instead yhat for a discrete approximation of y in an ODE integration, etc.

I really appreciate this in teaching, since it relieves students of the burden of learning to recognize both the chalkboard math and ASCII code conventions for the same quantity.

[rafael.guerra]

What a nightmare it would be if we replaced x with unknown in mathematical formulas or in code.

[kellertuer]

I agree with that; though there is a tradeoff of course, even calling it lambda requires that the reader of the code knows that that refers to Eigenvalues.
On the other hand the code is super-easy to read for all of us who know this convention in naming – and maybe if one reads the code and has to know about eigenvalues anyways – lambda is fine. And then of course also the UTF-8 – I also love to use those then, since it is so much more readable.

On the other hand, one maybe should not “invent” such short variables for own things too often unless clear from context line in the above sim::Simulation within nice short function.

[joa-quim]

\theta for potential temperature is fine
\ell for something down one page, is not. It looks pedantic to me.

[cvanaret]

Good point. In the end, I think the bottom line is: if you’re the only reader of the code, do whatever pleases you (and maybe regret it 3 months later). If not, work hard on the names.

[kellertuer]

Nice summary – maybe extended by: Know your (code-reading) audience If you are in a math/physics/… area where everyone knows some fixed variable convention – it makes code really beautiful to read (for the knowledgable wizard).

[uniment]

This is what the let statement is for, both in programming and in mathematical proofs: so that variables can have verbose descriptive identifiers in larger/global contexts, but short concise names within local contexts where we’ve specified what we’re talking about and our interest shifts toward manipulating the symbols.

And when that doesn’t cut it, we have module encapsulation too.