Skip to main content ↑ ↓
Topic: Need tip for scripting/coding readability. (Read 1397 times) previous topic - next topic
0 Members and 1 Guest are viewing this topic.

Need tip for scripting/coding readability.

Hello fellow coders/scripters. Well I'm not a coder, but I think it applies to it as well.

When naming variables or functions how do you balance between readability of the code/script and how detailed the variable names are?
As well as that in mix with commenting within the code/script and the proper way to do comments?

for example:
Code: [Select]
# var_name is for blah blah blah blah blah
var_name=value
vs
Code: [Select]
# this section is for blah and does blah
var_name_that_does_this_for_this_and_this_etc=value

I made some script for yambar status bar and it worked great, but the variables seemed to have long names.
Was thinking that if I don't do it that way it would be a problem for maintaining it later.

There's probably a sweet spot in the middle but I don't know where.

Samples for reference would also be appreciated.

Re: Need tip for scripting/coding readability.

Reply #1 –
What first comes to my mind is Rob Pike's excellent take on the subject: PDF, HTML. See in particular the sections "Variable names" and "Comments" . The whole essay is worth a read. It is C-specific and therefore occasionally somewhat technical, but there are universally applicable pieces of wisdom there for anyone writing anything code-like.

Re: Need tip for scripting/coding readability.

Reply #2 –
Definitely first one, with comment explaining much better than what long var name could do, keeping var_name short and somewhat descriptive.

Long variable names are attractive but, depending on what you do with them, code can quickly turn into

    var_name_that_does_this_for_this_and_this_etc_1 + var_name_that_does_this_for_this_and_this_etc_2

which is hard to read.

Re: Need tip for scripting/coding readability.

Reply #3 –
Quote from: lotuskip – on
What first comes to my mind is Rob Pike's excellent take on the subject: PDF, HTML. See in particular the sections "Variable names" and "Comments" . The whole essay is worth a read. It is C-specific and therefore occasionally somewhat technical, but there are universally applicable pieces of wisdom there for anyone writing anything code-like.

Thanks for this. I've read it and. While I don't get some of the refeneces like the Algol-68 report (I did looked it up but it's nearly 300 pages long.).

I did understand most concepts though. To put it into words, code the program in a bird's eye view. That's what I did with the long variable names, but I will try altering the same script into a more happy medium.


Quote from: dpx – on
Definitely first one, with comment explaining much better than what long var name could do, keeping var_name short and somewhat descriptive.

Long variable names are attractive but, depending on what you do with them, code can quickly turn into

    var_name_that_does_this_for_this_and_this_etc_1 + var_name_that_does_this_for_this_and_this_etc_2

which is hard to read.

Yeah that's the issue I was dealing with. As mentioned above I'll try rewriting my script.

Re: Need tip for scripting/coding readability.

Reply #4 –
You can usually find some style guides in the official documentation of the language you are using, different languages frequently follow different conventions.

Re: Need tip for scripting/coding readability.

Reply #5 –
Quote from: ####### – on
You can usually find some style guides in the official documentation of the language you are using, different languages frequently follow different conventions.

For reference, for the C languange. Would it be this? https://www.iso.org/standard/82075.html

Re: Need tip for scripting/coding readability.

Reply #6 –
There is a chapter on style in the GNU C Tutorial, which can be found online in various places and formats, here as a pdf:
https://www.it.uc3m.es/pbasanta/asng/course_notes/ctut.pdf
The GLIBC manual contains numerous code examples too, if not a specific style guide, e.g.:
https://sourceware.org/glibc/manual/latest/html_node/Calling-Glob.html
You should also check if any style guides are in place if you are modifying an existing project, and try to follow any conventions used even if they are not explicitly defined, they can vary quite widely:
https://www.kernel.org/doc/html/v4.10/process/coding-style.html

Re: Need tip for scripting/coding readability.

Reply #7 –
So I've read and did some changes. Thoughts?

Before:


After:


I think there could be improvements, but I'm not seeing it. I could be missing something. So I think external feedback would probably be better.

Re: Need tip for scripting/coding readability.

Reply #8 –
I think the bottom version looks much better, although it seems to me the comments are generally more helpful in the first version to explain what is happening.

Re: Need tip for scripting/coding readability.

Reply #9 –
Quote from: ####### – on
I think the bottom version looks much better, although it seems to me the comments are generally more helpful in the first version to explain what is happening.

Thanks man. I think this is a proper mix between the two: