How would you comment your script implementations?

[DoubleX]

Right now I'm commenting my script implementations this way(including basic version control):

Spoiler

# 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 |

For instance(DoubleX RMVXA Enhanced YSA Battle System: Classical AT:

Spoiler

  #----------------------------------------------------------------------------|  #  (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

  #----------------------------------------------------------------------------|  #  (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

I'll also comment the new instance variables. For instance(DoubleX RMVXA Enhanced YSA Battle System: Classical AT:

Spoiler

  #----------------------------------------------------------------------------|  #  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

I'll comment why I'd add and/or edit a class as well. For instance(DoubleX RMVXA Enhanced YSA Battle System: Classical AT:

Spoiler

#------------------------------------------------------------------------------|# * (New)Handles the battle atb clock bar in battle atb clock and turn window |#------------------------------------------------------------------------------|class ECATB_Clock_Bar < Viewport

#------------------------------------------------------------------------------|#  * (Edit)Reconstructs the the whole battle flow to control the atb system    |#------------------------------------------------------------------------------|class Scene_Battle < Scene_Base

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?

 

[Sixth]

I simply don't.


I used to make some comments when I started scripting, but soon realized that it just makes scripts longer than they actually are.


The main reason is, more scrolling down (like if 500-1000 lines are not enough already) and I find it unnecessary. I know what I coded, and that is enough for me.


If someone else wants to understand my code, well, I am not responsible for anyone in that regard. It's not like I write my code in a way that others could not understand it easily (with the given knowledge, of course).


If I edit someone else's code, now that is when I make a simple comment for myself only, so that I know that I added this and that, and if I will ever need to copy my changes or make them an addon, I can do it easily just by reading my comments. But even those comments won't say much, usually just "- Added by Sixth" or something like that. If I'm in a rush, I just write a bunch of comment signs (##########) at the end of the lines I wrote, it sticks out of the code that way.


Rarely, when I write something complex (note that complex for me might not be so complex for others), I simply just write a one-liner what that part of the method does exactly in case I forget it later and need to look it up. But it's a very rare occasion, and these comments do not follow any kind of format.


Bottom line, I write scripts because I enjoy writing them, I release them here so that anyone can use them (well, most of them anyway), but I don't really care if someone can understand my scripts or not.

 

[DoubleX]

I simply don't.

I used to make some comments when I started scripting, but soon realized that it just makes scripts longer than they actually are.

The main reason is, more scrolling down (like if 500-1000 lines are not enough already) and I find it unnecessary. I know what I coded, and that is enough for me.

If someone else wants to understand my code, well, I am not responsible for anyone in that regard. It's not like I write my code in a way that others could not understand it easily (with the given knowledge, of course).

If I edit someone else's code, now that is when I make a simple comment for myself only, so that I know that I added this and that, and if I will ever need to copy my changes or make them an addon, I can do it easily just by reading my comments. But even those comments won't say much, usually just "- Added by Sixth" or something like that. If I'm in a rush, I just write a bunch of comment signs (##########) at the end of the lines I wrote, it sticks out of the code that way.

Rarely, when I write something complex (note that complex for me might not be so complex for others), I simply just write a one-liner what that part of the method does exactly in case I forget it later and need to look it up. But it's a very rare occasion, and these comments do not follow any kind of format.

Bottom line, I write scripts because I enjoy writing them, I release them here so that anyone can use them (well, most of them anyway), but I don't really care if someone can understand my scripts or not.

So it probably means your codes are always so self-documenting that you can read them just find after several months, which is excellent(choosing not to write comments can also be an incentive to write self-documenting codes)

Also, your point about extra lines and size to the scripts due to comment is at least worth considering to me. For instance:

- Some users won't need them(after all, those comments are for script implementations only) and may find them so redundant that they want them removed from their copies at the very beginning(they might even think it's the scripters' responsibility to remove everything that are useless for them)

- Some scripters, like me(an incredibly nub one) have problems managing scripts that are too large for them. Even though being more proficient will likely be able to manage larger scripts, that usually takes time, while in some cases, tight deadlines have to be met so they've to be written anyway.

- Sometimes there might be cases where scripters will never ever need any other to even know what their scripts are doing. Of course justifying those cases mostly needs extremely solid reasons

On the other hand, if in some cases teamwork and/or external supports will probably take place, then commenting the script implementations likely becomes necessary.

I'm also interested in that, when you read someone else's codes with no comments, do you have any instance that you wanted those codes to have been commented instead?

 

[Sixth]

I can read my own code anytime, I just use my own logic to read it, since I have written it, that's all I need to do really.


Writing these comments for a 3000+ lines code would take hell of a lot time (even for an 1000+ lines code), which could have been spent on improving/expanding the code some more.


Yeah, teamwork might need some commenting, but what teamwork needs even more is a clean code. If you need to comment it for others to understand, than either the others are lacking the knowledge to understand the code or you made it over-complicated/not clean enough.


It's just my view on this, and it is the main reason why I don't work well in a team. I hate to explain my code to anyone, and I like to write codes alone. In a solo project, I am the one responsible for the code alone, but in a team project, the code can be broken by anyone in the team. I also don't like to depend on anyone else.


As for scripts not written by me, I usually understand them without comments. It's just a matter of tracing back method calls to learn how they work.


Sure, I don't understand all of it sometimes, but that is not because of the lack of comments. It is because I never did something like that, or I simply don't understand that particular class at all. One excellent example is Fiber, I have no idea how that class operates. I can use an existing Fiber instance, but I never managed to create a working Fiber class on my own (not that I need it, but it would be nice to learn it anyway). Even though I read many articles about it, I still don't get it, so a few more comments won't help me anyway, I guess.

 

[DoubleX]

I can read my own code anytime, I just use my own logic to read it, since I have written it, that's all I need to do really.

Writing these comments for a 3000+ lines code would take hell of a lot time (even for an 1000+ lines code), which could have been spent on improving/expanding the code some more.

Yeah, teamwork might need some commenting, but what teamwork needs even more is a clean code. If you need to comment it for others to understand, than either the others are lacking the knowledge to understand the code or you made it over-complicated/not clean enough.

It's just my view on this, and it is the main reason why I don't work well in a team. I hate to explain my code to anyone, and I like to write codes alone. In a solo project, I am the one responsible for the code alone, but in a team project, the code can be broken by anyone in the team. I also don't like to depend on anyone else.

As for scripts not written by me, I usually understand them without comments. It's just a matter of tracing back method calls to learn how they work.

Sure, I don't understand all of it sometimes, but that is not because of the lack of comments. It is because I never did something like that, or I simply don't understand that particular class at all. One excellent example is Fiber, I have no idea how that class operates. I can use an existing Fiber instance, but I never managed to create a working Fiber class on my own (not that I need it, but it would be nice to learn it anyway). Even though I read many articles about it, I still don't get it, so a few more comments won't help me anyway, I guess.

Good to know your scripting philosophy 

Just 1 potential edge case to consider:

Suppose for some reasons, you won't support some of your scripts anymore(for example, you might become inactive for quite a long time), and some requests are made to ask some other scripters to support them.

Some other scripters do try to solve those requests, but they failed to understand your codes(even if they're extremely self-documenting to you) so they can't solve them. What do you think about such situations if they would ever possibly exist?

While adding comments, even excellent one, still has to guarantee that any other will understand a bit of the codes, unless they're so poorly written that they're misleading or even deceiving, doing so likely at least slightly increases the chance and reduces the costs for the codes to be understood rather than misunderstood. Nevertheless, adding comments, which are probably liabilities themselves, does have its costs and risks, so it all comes down to balance and case analysis.

Of course, if the codes are self-documenting to the point that every other readers having related domain knowledge and scripting proficiency can easily understand it with just little effort, then that's another story

P.S.: When reading about opinions on code readability in the internet(I've searched for comments on such discussions/debates before opening this topic XD), it seems to me that, given the readers have related domain knowledge and coding proficiency, there are 2 relatively common views:

- 1 group feels/thinks that such readers should be willing and able to dry run the codes locally(or even globally) in order to understand them. If they're unable and/or unwilling to dry run them, then that's their problem.

- Another group feels/thinks that the codes should be able to be written in ways that are self-documenting(or clearly commented) enough for such readers. If they've to dry run the codes locally(or even globally) in order to understand them, then that's the codes' problem.

However, both agree that if readers have no related domain knowledge and/or coding proficiency, then they won't be able to understand the codes no matter how well they're written and/or documented.

Again, that's just what I've gathered so far

So I usually ask myself to write codes that are self-documenting enough for readers having related domain knowledge and scripting proficiency. To further play safe, I'll also try to add concise and precise comments. When someone can't understand my codes, I'll think that's my problem.

On the other hand, uptil now I've never ever complained for other codes' readability(and I never expected myself to understand them without dry running them first), as I always think that it's my problem.

That's just my philosophy lol

 

[Sixth]

If I become inactive for a very long time, than that will have it's reasons, and those reasons will be much higher on my priority list than to maintain my scripts, or even to care for them or for anyone else trying to understand/modify them.


So yeah, if I would disappear from this community, I wouldn't really care about anything related to it. After all, real life stuffs come first always, and I guess most of us agree on this point.


But until that happens, I am here to answer any questions if I can, be it about my scripts or others'.


I too agree on the part which says that if readers don't have sufficient knowledge, it doesn't matter how someone writes his/her codes, they won't understand it anyway.