1. Welcome to skUnity!

    Welcome to skUnity! This is a forum where members of the Skript community can communicate and interact. Skript Resource Creators can post their Resources for all to see and use.

    If you haven't done so already, feel free to join our official Discord server to expand your level of interaction with the comminuty!

    Now, what are you waiting for? Join the community now!

Dismiss Notice
This site uses cookies. By continuing to use this site, you are agreeing to our use of cookies. Learn More.

How to comment properly

Mar 28, 2020
How to comment properly
  • Why you are here
    You need to comment your code. Under any circumstances, not commenting your code will cause more problems.

    In this short tutorial, I will show the correct way of commenting code.


    Commenting
    [[ Show what it means ]]

    Generally, lines on the code speak for themselves
    example

    Code (Text):
    1.  
    2. function aPlusb(a: number, b: number) :: number:
    3.    return {_a}+{_b}
    4.  
    you don't need to comment about this since it is generally understandable by everyone

    However, you need to code on these types of code
    • code that has complex data structures
    • code that uses compact code expressions
    • code that seems to have unintuitive logic flow
    • and generally, every code that might need some extra explanation
    example code that needs comments
    Code (Text):
    1.  
    2. function ChatString_CutRight(t: text, l: integer) :: string:
    3.     set {_text::*} to ChatString_ColorToBlank({_t}) split at ""
    4.     set {_textl} to size of {_text::*}
    5.     delete {_text::%{_l}%}
    6.     set {_returntext} to ""
    7.     set {_pxl} to 0
    8.     loop {_text::*}:
    9.         set {_nextcharl} to ChatString_ReturnPixelLength(loop-value)
    10.         add {_nextcharl} to {_pxl}
    11.         if {_pxl} <= {_l}:
    12.             set {_returntext} to "%{_returntext}%%loop-value%"
    13.         else:
    14.             exit loop
    15.     set {_returntext} to substring of {_t} from 1 to length of {_returntext}
    16.     return {_returntext}
    17.  
    You could try to understand it but it's hard to read. Also, the names are arbitrary.

    So, should you comment as much as you can? no
    Here is a list of the comments you should not include
    Code (Text):
    1.  
    2. # comments that literally explain the code
    3. if {_hang} > 3: # this code will execute if hang is greater than 3
    4. # fix
    5. if {_hang} > 3: # check if player's total hangs are over 3 times => game over
    6.  
    7.  
    8. # comments that tell what the type of that line is
    9. trigger: # this is a trigger
    10. # fix
    11. trigger:
    12. # you should not comment on lines that are keywords and widely used.
    13. # commenting "this is a trigger" doesn't help anything
    14.  
    15.  
    16. # commenting useless information
    17. message "activated" to player # this code is just to show that the code is properly working therefore if it is not sent, the code has a problem
    18. # fix
    19. message "activated" to player # debug message
    20.  
    21.  
    22. # commenting after a long string
    23. set {_base64} to "
    24. TWFuIGlzIGRpc3Rpbmd1aXNoZWQsIG5vdCBvbmx5IGJ5IGhpcyByZWFzb24sIGJ1dCBieSB0aGlz
    25. IHNpbmd1bGFyIHBhc3Npb24gZnJvbSBvdGhlciBhbmltYWxzLCB3aGljaCBpcyBhIGx1c3Qgb2Yg
    26. dGhlIG1pbmQsIHRoYXQgYnkgYSBwZXJzZXZlcmFuY2Ugb2YgZGVsaWdodCBpbiB0aGUgY29udGlu
    27. dWVkIGFuZCBpbmRlZmF0aWdhYmxlIGdlbmVyYXRpb24gb2Yga25vd2xlZGdlLCBleGNlZWRzIHRo
    28. ZSBzaG9ydCB2ZWhlbWVuY2Ugb2YgYW55IGNhcm5hbCBwbGVhc3VyZS4=
    29. " # this is the text base64
    30. #fix
    31. # text base64 of paragraph
    32. set {_base64} to "
    33. TWFuIGlzIGRpc3Rpbmd1aXNoZWQsIG5vdCBvbmx5IGJ5IGhpcyByZWFzb24sIGJ1dCBieSB0aGlz
    34. IHNpbmd1bGFyIHBhc3Npb24gZnJvbSBvdGhlciBhbmltYWxzLCB3aGljaCBpcyBhIGx1c3Qgb2Yg
    35. dGhlIG1pbmQsIHRoYXQgYnkgYSBwZXJzZXZlcmFuY2Ugb2YgZGVsaWdodCBpbiB0aGUgY29udGlu
    36. dWVkIGFuZCBpbmRlZmF0aWdhYmxlIGdlbmVyYXRpb24gb2Yga25vd2xlZGdlLCBleGNlZWRzIHRo
    37. ZSBzaG9ydCB2ZWhlbWVuY2Ugb2YgYW55IGNhcm5hbCBwbGVhc3VyZS4="
    38.  
    39.  
    40. # commenting vague meanings
    41. set {_ytho} to "I--eiHiens" # F/Prt
    42. # fix
    43. set {_ytho} to "I--eiHiens" # format printing
    44.  
    45.  
    46. # and lastly,
    47. # excessive comments about your credits
    48. function thisFunc():
    49.     # CREDITS: SomeUsername
    50.     # DO NOT DISTRIBUTE
    51.     # ----------------------------------------
    52.     # created by: SomeUsername
    53.     # ----------------------------------------
    54.     # best code ever
    55.  
    56. # might add more examples later. last update 2020/2/5
    57.  

    Code from skUnity Discord
    Code (Text):
    1.  
    2. command /sharigan [<text>]: # The Command
    3.      trigger: #what Triggers it?
    4.          if player has permission "sharigan.use": #if player has permission then keep going
    5.              if {permsharigan.%player%} is not set: #if the variable it not set, well then
    6.                  set {permsharigan.%player%} to true #set it
    7.                  set {oldhelmet::%player%} to helmet of player # Store old helmet
    8.                  make player execute command "me Activated Sharigan" #just to show that its activated
    9.                  message " &f&k------ &7&lSharigan Activated 300s! &f&k------" #again to show its activated
    10.                  execute console command "effect give %player% minecraft:speed 1200 3" #give speed boost (just temp to see it work and it does)
    11.                  #set item data of player's helmet to "minecraft:diamond_shovel:430" #Set the helmet to our custom model
    12.                  set helmet of the player to a diamond helmet# test to see if it works
    13.                  wait 300 seconds #hold your horses
    14.                  if {permsharigan.%player%} is true: #if its still on then shut if off now
    15.                      make player execute command "shariganoff" #execute order 66
    16.                      stop #hammer time
    17.                  stop #x2
    18.              if {permsharigan.%player%} is true: #deactivate
    19.                  delete {permsharigan.%player%}
    20.                  execute console command "effect give %player% minecraft:speed 1 4"
    21.                  message " &f&k------ &7&lSharigan Deactivated &f&k------" #now its off
    22.                  stop
    23.          else:             message " &7>> &cYou have not awakened the Sharigan!" #no perms no useage
    24.  
    25.  
    You can see that the comments do help a bit but it still can be better

    Code (Text):
    1.  
    2. command /sharigan [<text>]:
    3.      trigger:
    4.          if player has permission "sharigan.use":
    5.             #if true, activate sharigan
    6.              if {permsharigan.%player%} is not set:
    7.                  # not set => activate
    8.                  # true => deactivate
    9.                  set {permsharigan.%player%} to true
    10.                  set {oldhelmet::%player%} to helmet of player
    11.                  # Store old helmet
    12.  
    13.                  make player execute command "me Activated Sharigan" # debug message
    14.  
    15.                  message " &f&k------ &7&lSharigan Activated 300s! &f&k------"
    16.  
    17.                  # give speed boost and change player's properties
    18.                  execute console command "effect give %player% minecraft:speed 1200 3"
    19.                  set item data of player's helmet to "minecraft:diamond_shovel:430
    20.                  # helmet custom model
    21.              
    22.                  set helmet of the player to a diamond helmet
    23.                  # debug
    24.  
    25.                  wait 300 seconds
    26.  
    27.                  if {permsharigan.%player%} is true:
    28.                      # true => shut if off
    29.                      make player execute command "shariganoff"
    30.                      stop
    31.                  stop
    32.              else if {permsharigan.%player%} is true:
    33.                  # deactivate
    34.                  delete {permsharigan.%player%}
    35.                  # change variable to not set state for further activation
    36.  
    37.                  execute console command "effect give %player% minecraft:speed 1 4"
    38.  
    39.                  message " &f&k------ &7&lSharigan Deactivated &f&k------"
    40.                  # off msg
    41.                  stop
    42.          else:
    43.              message " &7>> &cYou have not awakened the Sharigan!"
    44.              #no perm message
    45.  
    Here is an example of a decent commented code

    Code (Text):
    1. function ChatString_CutRight(t: text, l: integer) :: string:
    2.     # this function returns a text that cuts the text to the targeted pixel
    3.  
    4.     # set the array of text
    5.     set {_text::*} to ChatString_ColorToBlank({_t}) split at ""
    6.     set {_textl} to size of {_text::*}
    7.     delete {_text::%{_l}%}
    8.  
    9.     # the final return string
    10.     set {_returntext} to ""
    11.  
    12.     # set the total pixel length to 0
    13.     set {_pxl} to 0
    14.  
    15.     # loop every character and add it to the pixel count
    16.     loop {_text::*}:
    17.         set {_nextcharl} to ChatString_ReturnPixelLength(loop-value)
    18.  
    19.         add {_nextcharl} to {_pxl}
    20.  
    21.  
    22.         if {_pxl} <= {_l}:
    23.             # if condition is true; means we can add a new character to the result string
    24.             set {_returntext} to "%{_returntext}%%loop-value%"
    25.         else:
    26.             # if it exceeds exit the loop and process the return text
    27.             exit loop
    28.  
    29.     # because the return text has blank characters
    30.     set {_returntext} to substring of {_t} from 1 to length of {_returntext}
    31.  
    32.     # return the final text
    33.     return {_returntext}
    34.  



    Update log
    - 2020/2/5 created page
(1194 Views)
Last Modified: Mar 28, 2020 at 7:54 AM (Cached)