RPG Maker Forums
Right now I'm commenting my script implementations this way(including basic version control):
For instance(DoubleX RMVXA Enhanced YSA Battle System: Classical AT
:
I'll also comment the new instance variables. For instance(DoubleX RMVXA Enhanced YSA Battle System: Classical AT:
I'll comment why I'd add and/or edit a class as well. For instance(DoubleX RMVXA Enhanced YSA Battle System: Classical AT:
Ideally, the method name should be self-documenting enough to clearly show what the method creation/modification does and/or why that creation/modification exists, method contents should be self-documenting enough to clearly show how the method works and/or why they can serve the method's purpose, and variable names should be self-documenting enough to clearly show their roles within their scopes.
However, sometimes:
- Comprehending some codes needs exceptional scripting proficiency and some highly specialized domain knowledge, but some readers just don't have all those
- Some scripters(like me, an incredibly nub scripter) just isn't capable enough to write such ideally self-documenting codes yet, but they still have to write scripts(like having accepted a comission that pays well or being one of the scripters in a project, each of which are responsible for writing a different script that has to work with the others)
- There might be just some other reasons lol
That causes comments in script implementations to be needed or at least warranted.
On the side note, I seldom(if ever indeed) write comments just to cover the related domain knowledge, as I'd write a separate article about that and include its link in the script instead. Otherwise if x scripts uses the same domain knowledge, I'd have to repeat the same comment just to cover the same domain knowledge in all those x different scripts
I'll also keep the targeted audience in mind(some other scripters and/or even script users) when writing comments(like how much related domain knowledge and scripting proficiency they've), but it seems to me it's more about code readability in general(although properly commenting script implementation is itself an important part of code readability)
What do you think about commenting script implementations in general? How would you comment them if you would? Why would/wouldn't you comment them in the first place? Would you use dedicated documentation tools for this?
# 2. Method documentation |# - The 1st part informs which version rewritten, aliased or created this|# method |# - The 2nd part informs whether the method's rewritten, aliased or new |# - The 3rd part describes why this method's rewritten/aliased for |# rewritten/aliased methods or what the method does for new methods |# - The 4th part describes what the arguments of the method are |# - The 5th part describes how this method works for new methods only, |# and describes the parts added, removed or rewritten for rewritten or |# aliased methods only |# Example: |# #--------------------------------------------------------------------------| |# # (Version X+; Rewrite/Alias/New)Why rewrite/alias/What this method does | |# #--------------------------------------------------------------------------| |# # *argv: What these variables are |# # &argb: What this block is |# def def_name(*argv, &argb) |# # Added/Removed/Rewritten to do something/How this method works |# def_name_code |# # |# end # def_name |
: #----------------------------------------------------------------------------| # (v0.02c+; Alias)Frees up unnecessary memory usage upon battle end | #----------------------------------------------------------------------------| alias on_battle_end_ecatb on_battle_end def on_battle_end on_battle_end_ecatb # Added to clear all instance variables that are only used in battles ecatb_reset clear_ecatb_lambdas # end # on_battle_end
Code:
#----------------------------------------------------------------------------| # (New)Processes the on skill/item ok command for unison skills/items | #----------------------------------------------------------------------------| # actors: The unison actors # window: The window having the unison item def on_ecatb_unison_item_ok(actors, window) # Sets the unison item for all unison actors and picks the item targets $game_temp.battle_aid = item = window.item $game_party.last_item.object = item if item.is_a?(RPG::Item) skill = item.is_a?(RPG::Skill) actors.each { |actor| actor.input.set_skill(item.id) actor.last_skill.object = item if skill @status_window.draw_item(actor.index) } return select_enemy_selection if item.for_opponent? select_actor_selection if item.for_friend? # end # on_ecatb_unison_item_ok #----------------------------------------------------------------------------| # New public instance variables | #----------------------------------------------------------------------------| attr_accessor :actor_index # Accessed by Scene_Battle to setup actors attr_accessor :ecatb_can_esc # The party escape permission flag attr_reader :ecatb_actor_act_list # The list of actors that can act attr_reader :ecatb_battlers_def_sums # All method sums of all battlers attr_reader :action_battlers # Read by Scene_Battle to execute actions attr_reader hase # Read by Scene_Battle to get the battle phase #----------------------------------------------------------------------------| # New private instance variables | #----------------------------------------------------------------------------| # @ecatb_esc_cond: The party escape conditions # @ecatb_esc: The party escape attempt flag
hase # Read by Scene_Battle to get the battle phase #----------------------------------------------------------------------------| # New private instance variables | #----------------------------------------------------------------------------| # @ecatb_esc_cond: The party escape conditions # @ecatb_esc: The party escape attempt flag:#------------------------------------------------------------------------------|# * (New)Handles the battle atb clock bar in battle atb clock and turn window |#------------------------------------------------------------------------------|class ECATB_Clock_Bar < Viewport
Code:
#------------------------------------------------------------------------------|# * (Edit)Reconstructs the the whole battle flow to control the atb system |#------------------------------------------------------------------------------|class Scene_Battle < Scene_BaseHowever, sometimes:
- Comprehending some codes needs exceptional scripting proficiency and some highly specialized domain knowledge, but some readers just don't have all those
- Some scripters(like me, an incredibly nub scripter) just isn't capable enough to write such ideally self-documenting codes yet, but they still have to write scripts(like having accepted a comission that pays well or being one of the scripters in a project, each of which are responsible for writing a different script that has to work with the others)
- There might be just some other reasons lol
That causes comments in script implementations to be needed or at least warranted.
On the side note, I seldom(if ever indeed) write comments just to cover the related domain knowledge, as I'd write a separate article about that and include its link in the script instead. Otherwise if x scripts uses the same domain knowledge, I'd have to repeat the same comment just to cover the same domain knowledge in all those x different scripts
I'll also keep the targeted audience in mind(some other scripters and/or even script users) when writing comments(like how much related domain knowledge and scripting proficiency they've), but it seems to me it's more about code readability in general(although properly commenting script implementation is itself an important part of code readability)
What do you think about commenting script implementations in general? How would you comment them if you would? Why would/wouldn't you comment them in the first place? Would you use dedicated documentation tools for this?
Latest Threads
-
-
-
A way for events to recognize they are close to each other? (4 Viewers)- Started by Kelphy
- Replies: 2
-
Latest Profile Posts
Just beat the last of us 2 last night and starting jedi: fallen order right now, both use unreal engine & when I say i knew 80% of jedi's buttons right away because they were the same buttons as TLOU2 its ridiculous, even the same narrow hallway crawl and barely-made-it jump they do. Unreal Engine is just big budget RPG Maker the way they make games nearly identical at its core lol.
Can someone recommend some fun story-heavy RPGs to me? Coming up with good gameplay is a nightmare! I was thinking of making some gameplay platforming-based, but that doesn't work well in RPG form*. I also was thinking of removing battles, but that would be too much like OneShot. I don't even know how to make good puzzles!
one bad plugin combo later and one of my followers is moonwalking off the screen on his own... I didn't even more yet on the new map lol.
