Python parenthesis question - Overclock.net - An Overclocking Community

Forum Jump: 

Python parenthesis question

Reply
 
Thread Tools
post #1 of 18 (permalink) Old 10-11-2018, 12:26 PM - Thread Starter
New to Overclock.net
 
PhotonFanatic's Avatar
 
Join Date: Dec 2009
Posts: 1,878
Rep: 19 (Unique: 18)
Python parenthesis question

I've heard that "ideal code" doesn't have any comments. Sounds like a recipe for disaster. Why would ideal code have no comments in it? example: #A comment like this in the code for people to read if necessary.

"Executing execution.exe"
Bang for the buck
(12 items)
CPU
3570k @ 4.6Ghz @1.35v
Motherboard
Gigabyte Z77x UD3H
GPU
evga GTX 970 SSC
RAM
16Gb Gskill Ripjaws 2133Mhz @ 9-11-10-28
Hard Drive
Samsung Evo 850
Power Supply
Silverstone 900 watt
Cooling
Thermalright Ultra 120 Extreme
Case
Silverstone Raven (1st edition)
Operating System
Windows 10 Spy Delux
Monitor
Xstar 27" PLS 1440p
Keyboard
Wireless ergonomic
Mouse
Logisys Wireless trackball
▲ hide details ▲

Last edited by PhotonFanatic; 10-11-2018 at 12:36 PM. Reason: reasons
PhotonFanatic is offline  
Sponsored Links
Advertisement
 
post #2 of 18 (permalink) Old 10-22-2018, 07:06 AM
Computers <3
 
Rakanoth's Avatar
 
Join Date: Oct 2017
Posts: 134
Rep: 3 (Unique: 3)
I think what is meant there is that the code should not be over-complicated and be as much self-explanatory as possible. Of course, there will be always cases where you should definitely have comments.

Rakanoth is offline  
post #3 of 18 (permalink) Old 10-22-2018, 04:30 PM - Thread Starter
New to Overclock.net
 
PhotonFanatic's Avatar
 
Join Date: Dec 2009
Posts: 1,878
Rep: 19 (Unique: 18)
That makes sense. But could it be that they don't want the space taken up? Or maybe the space that a bunch of comments would take up, is negligible.

"Executing execution.exe"
Bang for the buck
(12 items)
CPU
3570k @ 4.6Ghz @1.35v
Motherboard
Gigabyte Z77x UD3H
GPU
evga GTX 970 SSC
RAM
16Gb Gskill Ripjaws 2133Mhz @ 9-11-10-28
Hard Drive
Samsung Evo 850
Power Supply
Silverstone 900 watt
Cooling
Thermalright Ultra 120 Extreme
Case
Silverstone Raven (1st edition)
Operating System
Windows 10 Spy Delux
Monitor
Xstar 27" PLS 1440p
Keyboard
Wireless ergonomic
Mouse
Logisys Wireless trackball
▲ hide details ▲
PhotonFanatic is offline  
Sponsored Links
Advertisement
 
post #4 of 18 (permalink) Old 12-01-2018, 12:26 PM
Computers <3
 
Rakanoth's Avatar
 
Join Date: Oct 2017
Posts: 134
Rep: 3 (Unique: 3)
Quote: Originally Posted by PhotonFanatic View Post
That makes sense. But could it be that they don't want the space taken up? Or maybe the space that a bunch of comments would take up, is negligible.

What do you mean by ''space taken up"? The comments will be ignored by the compiler and will have no influence on the compiled binary of the program.
Comments are good. Unnecessary comments are bad. There are very nice resources on how to write good comments. Every beginner will have difficult writing good comments. It is all OK.

Rakanoth is offline  
post #5 of 18 (permalink) Old 12-03-2018, 08:23 PM - Thread Starter
New to Overclock.net
 
PhotonFanatic's Avatar
 
Join Date: Dec 2009
Posts: 1,878
Rep: 19 (Unique: 18)
Quote: Originally Posted by Rakanoth View Post
What do you mean by ''space taken up"? The comments will be ignored by the compiler and will have no influence on the compiled binary of the program.
Comments are good. Unnecessary comments are bad. There are very nice resources on how to write good comments. Every beginner will have difficult writing good comments. It is all OK.
I meant in terms of the size of the program, once complete. With no comments, maybe it would be somewhat smaller.

"Executing execution.exe"
Bang for the buck
(12 items)
CPU
3570k @ 4.6Ghz @1.35v
Motherboard
Gigabyte Z77x UD3H
GPU
evga GTX 970 SSC
RAM
16Gb Gskill Ripjaws 2133Mhz @ 9-11-10-28
Hard Drive
Samsung Evo 850
Power Supply
Silverstone 900 watt
Cooling
Thermalright Ultra 120 Extreme
Case
Silverstone Raven (1st edition)
Operating System
Windows 10 Spy Delux
Monitor
Xstar 27" PLS 1440p
Keyboard
Wireless ergonomic
Mouse
Logisys Wireless trackball
▲ hide details ▲
PhotonFanatic is offline  
post #6 of 18 (permalink) Old 01-10-2019, 08:10 AM
New to Overclock.net
 
Join Date: Jun 2018
Location: Hendersonville, NC
Posts: 100
Rep: 0
To answer the question directly:

The best code is simple - it should be self explanatory, but that doesn't mean there should be no comments. Function names should define exactly what they do... But its hard to be perfect.. And, if you ever intend others to read your code and / or learn from it or maintain it ( such as in a business environment ) then you will need a coding standard and it must be adhered to, and comments will help the next person who comes along.

No comments means more wasted time to remember what something does if you come back to it years later... I have code still in use I wrote decades ago because I simplify logic into building blocks - porting code from one language to another is much easier when doing this ( see below regarding repetition, etc.. )..


If you want to make yourself think that your company won't fire you if you don't include comments - you are likely mistaken unless you are the best at your job ( but then you'd also include comments ) and underpaid.. Then, the employer won't give you a positive review when you apply elsewhere because you purposely made it difficult to go through all of the code to determine functionality for the next person for them to comment.


Even if the code is only for you - as I mentioned I am still using code I wrote decades ago ( and Intel is using a 40+ year old command architecture in their processors with additions if I recall correclty [ 8086? ] ) - it's best to include comments, especially if you do not have perfect recall.






If space was the problem, then everyone would use tabs instead of spaces to indent Python code.

For instance: A 1MB Python file indented using spaces is typically around 200KB when using tabs. A HUGE Difference.

Less chars means less to process as well.


I teach, so I always comment my code quite well - what pains me is when reviewing student code from a file named example.py and its so densely packed ( I prefer airy, ie x[ 'abc' ] instead of x['abc'] and when you have hundreds or thousands of lines which read like a book rather than code, it can be tiresome as we humans are good at pattern recognition - ie looking through indents, spacing, etc.. can help us interpret code more efficiently, but no spaces makes it harder to spot errors.

It's why we are albe to raed tihs and smeoihtng legnor eilsay - it's why we are able to read this and something longer easily... Our brain fixes the errors for us in order to make sense of it... So if you come across something close together without spaces and it starts and ends with the proper character, it's super easy to skip over.. For instance, def name( ):: can easily be overlooked with thousands of lines... Just as easily as def name( ) if you code with other languages... ), no comments, etc...

A few other things - when using tabs to indent code, you can easily, with most editors, change the size of spaces each tab character represents meaning if you prefer using 2 spaces, 4 spaces, 8, etc... you can easily set it... It may not be about preference either... Someone with visual deficits may find it a lot easier to code with a larger or smaller indentation and that can be done with a simple menu option or command.. Similarly for airy style of coding, it can help those with visual deficits, and make interpreting code that much more efficient for those without serious visual deficits.

All of this is related... Here are some more tips aside from using Tabs, the size-cost for not, etc..:


I urge you to develop or use a coding standard to ensure your code is written a specific way to help spot errors and to take advantage of how to brain processes text. Here's some of what can be defined... But, it revolves around the entire feel of the code - how it looks, variable naming techniques, commenting styles, and so much more...

In Python underscores have specific meaning, but my coding standard actually works with what I use... no underscores = global / file scope, 1 underscore is local / argument local / etc.., 2 underscores means an internal / private variable. CONSTants and ENUMs are always uppercase. I also use MAP_ and MAPR_ prefixes for CONSTant maps for ENUMs ( map and reverse map ) to lookup data and reverse it...

Using underscores means if there is an error, I know IMMEDIATELY know the scope the variable should be so if I see error _blah global is undefined or something, then I can clearly see _ means it should be a local so something is bleeding through, overwriting or some other issue which needs to be looked into - saving valuable time for debugging.

I have my own set of reserved variable names which are only used in certain scenarios - for instance in Garry's Mod Lua I use _p for Player Entity, _w for Weapon Ent, _ent for General Entity, _npc for NPC Ent, _vm for View Model Ent, _pos for Position ( uses Vector object ), _ang for Angle, and more... This means if I encounter an error with any of these, I know exactly what data-type is used without exception. There are a lot more.

For commenting, I use 2 blank spaces, then 3 lines of //s for each function with the center // having a description of the function. If the language doesn't use //s for comments, then I use 2 characters - for instance in Batch you can use ; so I use ;;s, Python uses # so I use ##s, and so on..

I am porting my function / class comment headers over using this system to include Java style @arg:, @return:, and so on style additions by adding a 4th and 5th line, with the 4th having @..: ... ( and if I add more than 1, then I always keep an empty comment line below the last one above the function / class line... I am adding this because I love automation and because of my reserved variables, etc.. I can combine all of the data from my coding standard and automatically create WIKI pages for everything I code and have them be incredibly accurate with no input, or very little input, from me.

So there are other benefits from using a coding standard and sticking with it aside from clarity, efficiency, automation, etc..

I usually format my coding standard layout using a few pages describing certain aspects and providing examples - it's a very quick way to show exactly what you mean.

Here's a very old version of it I have on Dropbox: https://www.dropbox.com/s/yjfrw9bqih...dards.lua?dl=0 -- This one has some of the differences between GMod Lua and Vanilla Lua

A few other notes - any time I repeat anything in code, I turn it into a helper function thus turning 2 or more lines into 1 each time...

I also change default functions which are ridiculous - for instance DrawRect( x, y, x2, y2 ) is much easier to code with ( and shorter math when overlapping to make a bordered rectangle ) DrawRect( x, y, w, h )... I don't overwrite the default functions, but I create new functions with those easier / more straight-forward logic..
Basically, instead of having to call DrawRect( x, y, w + x, y + x ) I can just call DrawRectEx( x, y, w, h ) and the rest is taken care of... In some cases the replaced functions need to be shifted by 1 so thats 1 less thing needed to be done done each time you call that function, etc..

Last edited by Acecool; 01-10-2019 at 08:21 AM.
Acecool is offline  
post #7 of 18 (permalink) Old 01-16-2019, 04:29 PM
New to Overclock.net
 
doritos93's Avatar
 
Join Date: Oct 2009
Location: Montreal
Posts: 2,309
Rep: 119 (Unique: 84)
Comments like "returns true if success, false if not" are totally useless



doritos93 is offline  
post #8 of 18 (permalink) Old 01-26-2019, 01:01 AM
New to Overclock.net
 
Join Date: Jun 2018
Location: Hendersonville, NC
Posts: 100
Rep: 0
Quote: Originally Posted by doritos93 View Post
Comments like "returns true if success, false if not" are totally useless
It depends. If you are teaching someone and they still have trouble interpreting what a boolean statement is actually doing, a comment saying something along the lines of - ( If the plugin isn't fully-loaded, returns True to prevent code below from executing ) - then that can be helpful for a newcomer even if the code is - [ if ( self.IsPluginActive( ) ) return True; ] - so they know that IsPluginActive is set when it is fully loaded, and that it blocks other code from executing.

It depends on how you formulate your code - do you formulate it so it can be used as a teaching tool... ie everything is explained. Or is it part of your coding standard to explain everything for this very reason? Do you want your code to look a certain way - ie commented but not a comment before every variable declaration, etc.... or do you use comments to isolate aspects...


For instance - Returns true if success, false if not can be useful... For instance - if you define a function: HasDoubleClicked or HasSingledClicked. An acceptable comment, to ensure your code has comment headers above functions, even if no comment is placed above the return statement could be: Returns True if Single-Click and Release was detected.... Or Returns True if Double-Click was Detected.

These comments fall across the nature of what you deemed useless, but they are concise and helpful by ensuring the code is uniform which improves readability, and reiterates what the function name tells you thereby providing confirmation as to the simplicity of what something does - this can be very helpful to new developers, or developers who are reviewing a piece of code they haven't before - not that they'd need the comment with the function name, but with the uniformity of the style it helps to ensure they can easily identify every aspect of the code.


Are there times when that comment may be in the way? I'm sure there are situations which are quite clear such as:

if ( _something == True ) return True; else return False; could be an example... Something short... And, that type of code, since _something would be a boolean, would look better as return _something == True; ( in the event it is None and you need a boolean -- or just return _something... or return _something or False; if you want to prevent a None return... etc.. )...


Don't discount comments while coding... If you have returned boolean statement with 20 components ( I'd recommend simplifying into helpers, but lets say it wasn't simplified because it was only ever used once in the code ) and the comment was returns True on success, false if not - that would be in the way because it doesn't provide any new information - unless you are incredibly new -, and likely useless, outside of formatting the code, because a boolean statement already returns True if the statement passes, False if not...

I'd likely avoid doing that, unless it was to be used as a placeholder, or was code with a primary focus on teaching.




In short, comments can have many purposes inside of code. The most common purpose is to describe, concisely, what the code does. Other purposes include being a placeholder for something, task-lists, notes, and even for formatting code to make everything easier to read - for instance I use 3 lines starting with comment notation with the center for a description for functions, classes / objects, etc... I always have 2 empty spaces above the top line / between functions / objects... With that simple technique, you know if you see 3 lines of comments with 2 blank lines what it is for... I use single line comments for documenting things in functions / code, or more lines if necessary but the top / bottom aren't empty. I also use the same 3 line notation as separating things in code such as at the top, the file header, then for config / declaration, imports, etc... then jumping into the rest of the code.

So when everything looks the same, it becomes very easy to skim the code and very easily identify what is what without having to read - and because of how our brains process text, this can be very beneficial.

Last edited by Acecool; 01-26-2019 at 01:08 AM.
Acecool is offline  
post #9 of 18 (permalink) Old 01-29-2019, 10:48 PM
RIP OCN
 
Join Date: Dec 2014
Posts: 599
Rep: 25 (Unique: 19)
Quote: Originally Posted by PhotonFanatic View Post
I've heard that "ideal code" doesn't have any comments. Sounds like a recipe for disaster. Why would ideal code have no comments in it? example: #A comment like this in the code for people to read if necessary.
Because good code can be readable to someone who has never seen a coding language before. Comments are still extremely useful, and you should never try to have zero comments in your code, but reducing comments is good.

Take this code for example:
Code:
class Helpers {

    void incrementByOne(int i) {
        i = i + 1;
    }

    void decrementByOne(int i) {
        i = i - 1;
    }

}

class Main {
    static void main() {
        int i = 0;
        Helpers helpers = new Helpers();
        
        helpers.incrementByOne(i);
        helpers.incrementByOne(i);
        helpers.decrementByOne(i);
    }
}
Adding comments is not needed, see below:

Code:
class Helpers {

    void incrementByOne(int i) {
        i = i + 1;  // increments integer i by 1
    }

    void decrementByOne(int i) {
        i = i - 1; // decrements integer i by 1
    }

}

class Main {
    static void main() {
        int i = 0; // start with i = 0
        Helpers helpers = new Helpers();
        
        helpers.incrementByOne(i); // increment i by 1
        helpers.incrementByOne(i); // increment i by 1
        helpers.decrementByOne(i); // decrement i by 1
    }
}
as you can see, the added comments have not helped, only cluttered the code, and forced more reading.
Basic example but you can probably see the point

Last edited by anti-clockwize; 01-29-2019 at 10:56 PM.
anti-clockwize is offline  
post #10 of 18 (permalink) Old 01-30-2019, 09:29 AM
New to Overclock.net
 
doritos93's Avatar
 
Join Date: Oct 2009
Location: Montreal
Posts: 2,309
Rep: 119 (Unique: 84)
Quote: Originally Posted by Acecool View Post
Quote: Originally Posted by doritos93 View Post
Comments like "returns true if success, false if not" are totally useless
It depends. If you are teaching someone and they still have trouble interpreting what a boolean statement is actually doing, a comment saying something along the lines of - ( If the plugin isn't fully-loaded, returns True to prevent code below from executing ) - then that can be helpful for a newcomer even if the code is - [ if ( self.IsPluginActive( ) ) return True; ] - so they know that IsPluginActive is set when it is fully loaded, and that it blocks other code from executing.

It depends on how you formulate your code - do you formulate it so it can be used as a teaching tool... ie everything is explained. Or is it part of your coding standard to explain everything for this very reason? Do you want your code to look a certain way - ie commented but not a comment before every variable declaration, etc.... or do you use comments to isolate aspects...


For instance - Returns true if success, false if not can be useful... For instance - if you define a function: HasDoubleClicked or HasSingledClicked. An acceptable comment, to ensure your code has comment headers above functions, even if no comment is placed above the return statement could be: Returns True if Single-Click and Release was detected.... Or Returns True if Double-Click was Detected.

These comments fall across the nature of what you deemed useless, but they are concise and helpful by ensuring the code is uniform which improves readability, and reiterates what the function name tells you thereby providing confirmation as to the simplicity of what something does - this can be very helpful to new developers, or developers who are reviewing a piece of code they haven't before - not that they'd need the comment with the function name, but with the uniformity of the style it helps to ensure they can easily identify every aspect of the code.


Are there times when that comment may be in the way? I'm sure there are situations which are quite clear such as:

if ( _something == True ) return True; else return False; could be an example... Something short... And, that type of code, since _something would be a boolean, would look better as return _something == True; ( in the event it is None and you need a boolean -- or just return _something... or return _something or False; if you want to prevent a None return... etc.. )...


Don't discount comments while coding... If you have returned boolean statement with 20 components ( I'd recommend simplifying into helpers, but lets say it wasn't simplified because it was only ever used once in the code ) and the comment was returns True on success, false if not - that would be in the way because it doesn't provide any new information - unless you are incredibly new -, and likely useless, outside of formatting the code, because a boolean statement already returns True if the statement passes, False if not...

I'd likely avoid doing that, unless it was to be used as a placeholder, or was code with a primary focus on teaching.




In short, comments can have many purposes inside of code. The most common purpose is to describe, concisely, what the code does. Other purposes include being a placeholder for something, task-lists, notes, and even for formatting code to make everything easier to read - for instance I use 3 lines starting with comment notation with the center for a description for functions, classes / objects, etc... I always have 2 empty spaces above the top line / between functions / objects... With that simple technique, you know if you see 3 lines of comments with 2 blank lines what it is for... I use single line comments for documenting things in functions / code, or more lines if necessary but the top / bottom aren't empty. I also use the same 3 line notation as separating things in code such as at the top, the file header, then for config / declaration, imports, etc... then jumping into the rest of the code.

So when everything looks the same, it becomes very easy to skim the code and very easily identify what is what without having to read - and because of how our brains process text, this can be very beneficial.
I thought it obvious that I meant comments like that in PRODUCTION code are useless.

I don't expect the programmer that came before me to explain the fundamentals of programming. I'd rather they explain the specific business logic behind arbitrary decisions, you know, stuff I can't find in a book

If you spend time commenting production code with stuff like "returns true if double or single click, false if no click" then maybe the methods themselves need to be reworked such that they can explain themselves



doritos93 is offline  
Reply

Quick Reply
Message:
Options

Register Now

In order to be able to post messages on the Overclock.net - An Overclocking Community forums, you must first register.
Please enter your desired user name, your email address and other required details in the form below.
User Name:
If you do not want to register, fill this field only and the name will be used as user name for your post.
Password
Please enter a password for your user account. Note that passwords are case-sensitive.
Password:
Confirm Password:
Email Address
Please enter a valid email address for yourself.
Email Address:

Log-in



Currently Active Users Viewing This Thread: 1 (0 members and 1 guests)
 
Thread Tools
Show Printable Version Show Printable Version
Email this Page Email this Page


Forum Jump: 

Posting Rules  
You may post new threads
You may post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is On
HTML code is Off
Trackbacks are Off
Pingbacks are Off
Refbacks are Off