Struanmcd
|
  |
| Joined: 19 Sep 2008 |
| Total Posts: 369 |
|
|
| 23 Feb 2013 10:17 AM |
Here's a script which I have found in a Minigame Set, I've decided to comment it, to test myself.
Could you please feedback on how accurate my commenting is? Thanks:
Code is below:
function ChildAdded(child) -- A function which will be called when something is added to the workspace print("Child Has been Added") -- Let us know that something has been added to the Workspace if string.sub(child.Name, 1, 9) == "Mini Game" then -- If the object's name is "Mini Game"xxx then print("Mini Found") -- Confirm that what is added is a minigame wait(15) -- Wait 15 seconds, I assume that this is how long it will take for the minigame print("Done Waiting") -- Confirm that we've done waiting ChildWK = game.Players:GetChildren() -- Create a table containing the players for i=1, #ChildWK do -- Iterate through the table if game.Workspace:findFirstChild(ChildWK[i].Name) then -- Find the physical player object in the Workspace if game.Workspace:findFirstChild(ChildWK[i].Name).ForceField then -- Find the forcefield game.Workspace:findFirstChild(ChildWK[i].Name).ForceField:remove() -- Remove the forcefield else print("No FF") -- If the player doesn't have a forcefield, remove it end else print("No Body") -- If the player doesn't exist in the workspace, but exists in the players section, print this end end end end game.Workspace.ChildAdded:connect(ChildAdded) -- Connection line
|
|
|
| Report Abuse |
|
|
adark
|
  |
| Joined: 13 Jan 2008 |
| Total Posts: 6412 |
|
|
| 23 Feb 2013 11:10 AM |
The thing about comments is that the 'perfect' code should never need them. You should only ever use them to explain *why* you did something, and if the code explains itself, ex. wait(15), then no comment is necessary.
From that, you can remove all of the comments in there, as none of the code you have written is ambiguous. |
|
|
| Report Abuse |
|
|
|
| 23 Feb 2013 11:13 AM |
"Find the forcefield" and etc is unnecessary. It should be obvious. For instance print("No FF") should NEVER need a comment. If it does, then your CODE needs fixing, e.g., print("The player doesn't have a forcefield") (If you need that much output)
'ChildAdded' for instances OUGHT to be an self-explanatory name. It doesn't need a comment except to explain WHAT it does to new objects. |
|
|
| Report Abuse |
|
|
Struanmcd
|
  |
| Joined: 19 Sep 2008 |
| Total Posts: 369 |
|
|
| 23 Feb 2013 11:17 AM |
I didn't write the code, I am commenting on the code to ensure I know what is happening. The purpose of this thread is to check to see if the comments reflect what the code is actually doing. If they don't, it means that there is a hole in my knowledge, which I need to go and revise.
I am asking, are my comments correct? I didn't write the code, and I am testing my understanding.
Thanks,
Struanmcd |
|
|
| Report Abuse |
|
|
adark
|
  |
| Joined: 13 Jan 2008 |
| Total Posts: 6412 |
|
|
| 23 Feb 2013 11:21 AM |
| You understand the code fine, we're just trying to inform you of the proper way to use comments. |
|
|
| Report Abuse |
|
|
Struanmcd
|
  |
| Joined: 19 Sep 2008 |
| Total Posts: 369 |
|
|
| 23 Feb 2013 11:22 AM |
| I understand now. Thanks for the help! |
|
|
| Report Abuse |
|
|
|
| 23 Feb 2013 11:23 AM |
Yes, you got it right, except for one nit picky detail:
for i=1, #ChildWK do -- Iterate through the table
Strictly speaking, this does not iterate through the table. It only moves 'i' through the length of the table. While it's purpose is, obviously, to iterate through, 'i' could be used to do any number of things, not just be used in the table (although in this case it is).
Commenting is as necessary to programming well as everything else. So, no, you aren't commenting "correctly" but you are understanding the code. |
|
|
| Report Abuse |
|
|
Struanmcd
|
  |
| Joined: 19 Sep 2008 |
| Total Posts: 369 |
|
|
| 23 Feb 2013 11:35 AM |
Thanks for pointing that out. Is there a resource I can look at which demonstrates proper commenting procedure?
Thanks |
|
|
| Report Abuse |
|
|
pwnedu46
|
  |
| Joined: 23 May 2009 |
| Total Posts: 7534 |
|
|
| 23 Feb 2013 11:52 AM |
| Because comments are for you (or whoever else reads your code) alone, there isn't really "procedure" for it. I only comment things that are not obvious at first glance or things that can easily be misinterpreted. Too many comments make your code hard to read. |
|
|
| Report Abuse |
|
|
Struanmcd
|
  |
| Joined: 19 Sep 2008 |
| Total Posts: 369 |
|
|
| 23 Feb 2013 12:55 PM |
That complements what I have learned with other languages. Comments are meant to clear up ambiguous areas, but I have fallen into the habit of putting too much comments into code anyway.
|
|
|
| Report Abuse |
|
|