Readability issues in this project

[glemin]

Hello,

When working on the project I came across a lot of readablility issues. I discussed this with couple of friends who work in the industry (one is a C++ developer in Antwerp, and the other is good friend of me now Java developing in Norway), and they both agreed on the fact that click has readability issues.

The main concern is the fact that most variable names are extremely short. For something as a packet it doesn't matter if you call it p (although I think most software engineers would prefer packet). But there are a lot of other variables which are extremely short and let you lose time.

The C++ developer from Antwerp said that they used even extremely long variable names. It is better to use longer names, because typing a name doesn't take you much time. And a clear name can save other developers a lot of time. Underlying a long or short name are just the same, the compiler abstracts this away so they didn't understand the point of using such short names oftentimes. "I think network developers need to learn some software engineering" joked my Antwerp friend, also pointing out that other network code you find online is oftentimes extremely messy written with short variable names.

Just to give you some examples,

static String
unparse_word(int type, int proto, const String &word)
{
    String tn = IPFilter::Primitive::unparse_type(0, type);
    String tr = IPFilter::Primitive::unparse_transp_proto(proto);
    if (tn)
    tn += " ";
    if (tr || (word && tn))
    tr += " ";
    return tn + tr + word;
}

What are tn and tr? That is just too short to understand, and it doesn't help readability.

void
IPFilter::Primitive::clear()
{
  _type = _srcdst = 0;
  _transp_proto = UNKNOWN;
  _data = 0;
  _op = OP_EQ;
  _op_negated = false;
}

Why write _op and _op_negated if you can just use _operator and _operator_negated ? Because otherwise people don't know what it means, it could have been optional, optimal, optimization, ... .

Same with OP_EQ, it is much better to use OPERATOR_OF_TYPE_EQUAL or something like that. Just make it as clear as possible. Better use a few words too much, than words too little.

An other example,

void
IPFilter::static_initialize()
{
    dbs[0] = new StaticNameDB(NameInfo::T_IPFILTER_TYPE, String(), type_entries, sizeof(type_entries) / sizeof(type_entries[0]));
    dbs[1] = new StaticNameDB(NameInfo::T_TCP_OPT, String(), tcp_opt_entries, sizeof(tcp_opt_entries) / sizeof(tcp_opt_entries[0]));
    NameInfo::installdb(dbs[0], 0);
    NameInfo::installdb(dbs[1], 0);
}

The usage of db is fine, it is a well known shortcut. But what is dbs, is it data base system, data base static? but why not write static_db then?

Or this example,

uint32_t data = _u.u;

These things can cost you a lot of time, and also can keep other developers out. It is always better to use names that are clear, and maybe even a bit too long, but you help the others so much by using clear variable names.

So maybe we can change this, and use clearer variable names from now on. Also having at least an @brief for each functions seems a must to me, if we want to work together on such a big project. There is also no point in for instance abbreviating the word "word" into "wd", which is an abstract code word that could just have meant litteraly everything from "wood" to "wild".

I also want to keep this project alive, attract more developers (e.g. by having clean code with longer variable names) because I really believe that this is one of the greatest projects ever done, and still can be extended in so many beautiful ways. If we could set up some action groups to replace the variable names by longer and more readable names, we can already accomplish a great thing.

Regards, Glenn Minne

[ahenning]

Glenn, don't you think your posts might sound a bit like "teaching grandma to suck eggs"?

"I have a friend" that joked software engineers talk a lot but don't do much. While you have a couple good talking points which I agree with, I am quite sure renaming variables are on the low end of the priority list for most. How about taking the initiative and update a couple existing elements to illustrate by example.

[glemin]

Hello,

I don't know how it sounds. "Sucking eggs" is not really something I would say to my grand ma, or she might think I have Tourette.

But I certainly want to change some of the variable names, so I will make work of that. :) Yea, maybe "your friend" is right, let's do some work. I will make commits soon.

Ps: I didn't want to offend others, sometimes it is hard to find the right tone!

Op maandag 14 maart 2016 heeft ahenning notifications@github.com het volgende geschreven:

Glenn, don't you think your posts might sound a bit like "teaching grandma to suck eggs"?

"I have a friend" that joked software engineers talk a lot but don't do much. While you have a couple good talking points which I agree with, I am quite sure renaming variable are on the low end of the priority list for most. How about taking the initiative and update a couple existing elements to illustrate by example.

— Reply to this email directly or view it on GitHub https://github.com/kohler/click/issues/243#issuecomment-196489947.

[glemin]

Pss: This is the same tone my parents use to me the whole time. Not that I particularly like the tone, but if you know no othet tone it feels hard to write it otherwise. I will think about what I write in the future.

When I tell my parents I don't want to be handled that rough they tell me: "What do I need to do? Tell you, well done, that was a magnificent job, keep working like that". I always try to get them act otherwise but then my mother calls me a "weakling" who can't handle critique.

Well, you shouldn't blame my parents. We are from a typical working class family, my father works in retail and gets offended a lot, my mother got offended a lot in life, and the Belgian equivalent of Fox they watch tells them that being though on each other feelings is the norm, or bosses treating their lowly educated employees in retail badly. So if something is to blame, it is the media keeping families down for generations and keeping them out of college for so long (by demoralizing each other/spreading propaganda that they are born less smart so people give them lesd attention). :)

But I will do my best, I will promise that!

Op dinsdag 15 maart 2016 heeft Glenn Minne glenn.minne@gmail.com het volgende geschreven:

Hello,

I don't know how it sounds. "Sucking eggs" is not really something I would say to my grand ma, or she might think I have Tourette.

But I certainly want to change some of the variable names, so I will make work of that. :) Yea, maybe "your friend" is right, let's do some work. I will make commits soon.

Ps: I didn't want to offend others, sometimes it is hard to find the right tone!

Op maandag 14 maart 2016 heeft ahenning <notifications@github.com javascript:_e(%7B%7D,'cvml','notifications@github.com');> het volgende geschreven:

Glenn, don't you think your posts might sound a bit like "teaching grandma to suck eggs"?

"I have a friend" that joked software engineers talk a lot but don't do much. While you have a couple good talking points which I agree with, I am quite sure renaming variable are on the low end of the priority list for most. How about taking the initiative and update a couple existing elements to illustrate by example.

— Reply to this email directly or view it on GitHub https://github.com/kohler/click/issues/243#issuecomment-196489947.

[glemin]

Psss: Teaching grandma sucks eggs really sounds aweful in Europe. Only the word "sucks" alone could bring out problems. Here in Belgian swearing is a bad thing, not only in working class but also in tbe higher classes.

Saying possibly sexual related words is even a bigger taboo. When they here look to the US they are like "wow they swear a lot". When Donald Trump talked about his penis, the heads exploded. The Socialist-leaning newspaper called it "Extremely low politics". And they really disgusted this sort of talk. Talking about your penis is extremely bad in Europe, also in left wing circles.

Just to give you some overseas information, you might find interesting. :)

Op dinsdag 15 maart 2016 heeft Glenn Minne glenn.minne@gmail.com het volgende geschreven:

Pss: This is the same tone my parents use to me the whole time. Not that I particularly like the tone, but if you know no othet tone it feels hard to write it otherwise. I will think about what I write in the future.

When I tell my parents I don't want to be handled that rough they tell me: "What do I need to do? Tell you, well done, that was a magnificent job, keep working like that". I always try to get them act otherwise but then my mother calls me a "weakling" who can't handle critique.

Well, you shouldn't blame my parents. We are from a typical working class family, my father works in retail and gets offended a lot, my mother got offended a lot in life, and the Belgian equivalent of Fox they watch tells them that being though on each other feelings is the norm, or bosses treating their lowly educated employees in retail badly. So if something is to blame, it is the media keeping families down for generations and keeping them out of college for so long (by demoralizing each other/spreading propaganda that they are born less smart so people give them lesd attention). :)

But I will do my best, I will promise that!

Op dinsdag 15 maart 2016 heeft Glenn Minne <glenn.minne@gmail.com javascript:_e(%7B%7D,'cvml','glenn.minne@gmail.com');> het volgende geschreven:

Hello,

I don't know how it sounds. "Sucking eggs" is not really something I would say to my grand ma, or she might think I have Tourette.

But I certainly want to change some of the variable names, so I will make work of that. :) Yea, maybe "your friend" is right, let's do some work. I will make commits soon.

Ps: I didn't want to offend others, sometimes it is hard to find the right tone!

Op maandag 14 maart 2016 heeft ahenning notifications@github.com het volgende geschreven:

Glenn, don't you think your posts might sound a bit like "teaching grandma to suck eggs"?

"I have a friend" that joked software engineers talk a lot but don't do much. While you have a couple good talking points which I agree with, I am quite sure renaming variable are on the low end of the priority list for most. How about taking the initiative and update a couple existing elements to illustrate by example.

— Reply to this email directly or view it on GitHub https://github.com/kohler/click/issues/243#issuecomment-196489947.

[glemin]

Last thing. Maybe this last post might or might not interest you, and maybe I gambled here wrongly.

What I still wanted to say is that people don't need to pin down too much on first impressions. People need time to adopt to the current context they are in, and this is here not different.

The time it takes to adopt, well that might depend on the current situation the person's in, his past experienced and so on, but also on his or her motivation and willingness to adapt to the more "superior" situation.

Although I might not able to adapt my parents, for reasons that are totally unclear to me, I will certainly adapt here, because I myself want to use the respectful way of talking, also wanting to be treated thay way as well.

For some reason having being years treated badly at work, having to blindly accept orders of your bosses for your entire life without opportunities to get up in the company, and having right wing working class media that normalises this or - in Belgium - even falsely claims that this is the way the higher classes talk to each other as well, creates this non resistable preference of many working class parents to keep offending their kids "because this is just the way it is, also in big life", undermining the mental capacities of their kids, and high class people assuming that they would have been in the working class kids' situation they would have made it , though tough, because they were born smart and those kids were born less smart.

This is a false assumption though, leaving the corrupt system of parents bashing down their children and leaving them as slow uneducated no confidence learners. Not becaude they had bad genes, no, because of mean evil right wing decissions and culture to keep the same people down.

The only way to still make it then, with militaristic / or working class parents, is to take Ritalin (which makes you feel happy), until you are old enough to move to college and you don't need to see them less frequently. Though I live again with my parents for 2 years, and this reversed some of the things, but this time I am not taking Ritalin anymore but I spend as much time possible at college.

I am not born dumb... I am born with parents that prevent proper studying. This rule applies to all working class people who are all smart enough for college, but get hold back by mean greedy politics undermining people's potential. If everyone can learn to ride a bicycle, everyone can learn to read, also everyone can do college with the proper support and no downtalk.

If at the same time people are willing to invest time in the ones who come from a worse situation and change those situations and the system that actively creates those situations, we aren't far away of a system with an extremely well educated force and lots of scientific progress is on the way then. :)

Op dinsdag 15 maart 2016 heeft Glenn Minne glenn.minne@gmail.com het volgende geschreven:

Psss: Teaching grandma sucks eggs really sounds aweful in Europe. Only the word "sucks" alone could bring out problems. Here in Belgian swearing is a bad thing, not only in working class but also in tbe higher classes.

Saying possibly sexual related words is even a bigger taboo. When they here look to the US they are like "wow they swear a lot". When Donald Trump talked about his penis, the heads exploded. The Socialist-leaning newspaper called it "Extremely low politics". And they really disgusted this sort of talk. Talking about your penis is extremely bad in Europe, also in left wing circles.

Just to give you some overseas information, you might find interesting. :)

Op dinsdag 15 maart 2016 heeft Glenn Minne <glenn.minne@gmail.com javascript:_e(%7B%7D,'cvml','glenn.minne@gmail.com');> het volgende geschreven:

Pss: This is the same tone my parents use to me the whole time. Not that I particularly like the tone, but if you know no othet tone it feels hard to write it otherwise. I will think about what I write in the future.

When I tell my parents I don't want to be handled that rough they tell me: "What do I need to do? Tell you, well done, that was a magnificent job, keep working like that". I always try to get them act otherwise but then my mother calls me a "weakling" who can't handle critique.

Well, you shouldn't blame my parents. We are from a typical working class family, my father works in retail and gets offended a lot, my mother got offended a lot in life, and the Belgian equivalent of Fox they watch tells them that being though on each other feelings is the norm, or bosses treating their lowly educated employees in retail badly. So if something is to blame, it is the media keeping families down for generations and keeping them out of college for so long (by demoralizing each other/spreading propaganda that they are born less smart so people give them lesd attention). :)

But I will do my best, I will promise that!

Op dinsdag 15 maart 2016 heeft Glenn Minne glenn.minne@gmail.com het volgende geschreven:

Hello,

I don't know how it sounds. "Sucking eggs" is not really something I would say to my grand ma, or she might think I have Tourette.

But I certainly want to change some of the variable names, so I will make work of that. :) Yea, maybe "your friend" is right, let's do some work. I will make commits soon.

Ps: I didn't want to offend others, sometimes it is hard to find the right tone!

Op maandag 14 maart 2016 heeft ahenning notifications@github.com het volgende geschreven:

Glenn, don't you think your posts might sound a bit like "teaching grandma to suck eggs"?

"I have a friend" that joked software engineers talk a lot but don't do much. While you have a couple good talking points which I agree with, I am quite sure renaming variable are on the low end of the priority list for most. How about taking the initiative and update a couple existing elements to illustrate by example.

— Reply to this email directly or view it on GitHub https://github.com/kohler/click/issues/243#issuecomment-196489947.

[kohler]

Thank you for the compliment about this project!

I'm very happy that Click has survived for as long as it has, even though, for personal reasons, I no longer choose to spend much time on active maintenance. However, I think it's incorrect to say that short variable names are preventing it from achieving greater acceptance.