Artistic source code via comments

[Tsukihime]

I don't know about you, but I like to toss excessive amounts of dashed lines throughout my code because I think it looks more artistic.

 #-----------------------------------------------# Some comment#===============================================def some_method  # codeend#===============================================# Some other comment, though unnecessary#-----------------------------------------------

To me that looks so much more cooler than simply

# some commentdef some_method  # codeend

 

[TheoAllen]

If the code is complex, I usually divide the method into parts

#-------------------------------------------------------------------------------# * New/Alias/Overwrite method : method name# Add some descriptions if necessary#-------------------------------------------------------------------------------def some_method    # First step. Comment here  statement_1  statement_2  statement_3    # Second step.  statement_4  statement_5  statement_6    # Third step. Why loop is necessary?  loop do    statement_7    statement_8    statement_9  end    return valueend

 

[Venka]

MIne is a cross between a few different scripts I studied trying to learn with a few of my own things.. Most folks will recognize the Yanfly style comments (at the time I was trying to learn he has the most scripts out to learn from).

So I like to label everything.. the class, attr_'s, methods, etc. Each type of info has it's own symbol so I can look at it with a glance and know what type it is:

Here's some code pulled from one of my scripts:

#==============================================================================# ■ RPG::BaseItem#==============================================================================class RPG::BaseItem #---------------------------------------------------------------------------- # Public Instance Variables #---------------------------------------------------------------------------- attr_accessor :tool #---------------------------------------------------------------------------- # ○ new method: load_craft_tool_notetag #---------------------------------------------------------------------------- def load_craft_tool_notetag @tool = false self.note.split(/[\r\n]+/).each do |line| case line when Venka::Notetag::Tool; @tool = true end end endendNow when a method is already defined somewhere.. Like I'm overwriting/alias an existing method or just upgrading it from the parent class then I do one of these (just the "alias" can be switched with upgraded or overwritten, but I know by the solid circle symbol that its something that already exists one way or another):

#---------------------------------------------------------------------------- # ● alias method: initialize #---------------------------------------------------------------------------- alias :shop_crafting_ini :initialize def initialize shop_crafting_ini .... endI like to use the symbols to alias as it's another visual clue since the color of the text changes.

And here's my cheat sheet for copy and paste that I keep in nearly every project of mine..

Spoiler

#==============================================================================# ▼ Script_Name - version_1.0                               Updated: mm/dd/2014#   author: #==============================================================================# - Introduction -#------------------------------------------------------------------------------#  Description of script's purpose.#------------------------------------------------------------------------------# - Instructions -#------------------------------------------------------------------------------#------------------------------------------------------------------------------# - Terms -#------------------------------------------------------------------------------#==============================================================================# ■ ClassName#==============================================================================  #=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-  # - General Settings -  #----------------------------------------------------------------------------  # Detailed instructions for setting up this area of the script.  #=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-    #----------------------------------------------------------------------------  # ♦ Public Instance Variables  #----------------------------------------------------------------------------  # ● alias method: method_name  #----------------------------------------------------------------------------  # ● overwrite method: method_name  #----------------------------------------------------------------------------  # ● upgraded method: method_name  #----------------------------------------------------------------------------  # ○ new method: method_name  #----------------------------------------------------------------------------

 

[tyler.kendrick]

I can't tell if you're begin facetious or not.  

Although, I really do like seeing whitespace and comment blocks separating related blocks of code for easier skimming.

I usually use "#===" for classes and "#---" for methods.

 

[_Shadow_]

Having such lines makes the code more easy to understand by human.

A good piece of code is great for machines to run it and also easy for a human to understand.

Good examples of such a great code is Luna Engine, Yami's scripts and Yanfly's scripts.

So a good piece of code is a well documented one.

Imagine now you, doing stuff to make it even more easy to the eye to read.

That's what you do here.

So it seems to me like a good thing in the first place.

One thing to be careful with, is consistency.

Your separation lines and spaces must follow always the same pattern.

Make a protocol, stick into it and yes. This is great!

This is just the tip of the iceberg about code as art.

Check THIS out!

 

[Selchar]

It's all over the base scripts.  There are points when I think there's just too much of it(the bigger scripts or bigger classes).  I'm sure there's a happy medium somewhere, overall tho everyone has their preferences in how they wish to write their code, or how they'd like to read it.  Can't satisfy everyone.

 

[cabfe]

I should really take lessons from you people, as my code is such a mess

It's riddled my crude debug lines (ie. a lot of "puts" and "printf") that I keep in case I need more debugging later.

And some commented test lines that I'm not confident enough to delete.

I think I'll make another pass over my scripts to clean them up a little. I feel ashamed .

 

[_Shadow_]

I should really take lessons from you people, as my code is such a mess

It's riddled my crude debug lines (ie. a lot of "puts" and "printf") that I keep in case I need more debugging later.

And some commented test lines that I'm not confident enough to delete.

I think I'll make another pass over my scripts to clean them up a little. I feel ashamed .

Someone is talking in C

Well you should just make it a habit.

Documenting everything.

I once wrote a piece of code and then left if for 6 months.

When I found it again, yeah I forgot about it lol, I couldn't understand what exactly it was doing, what was it all about and how I could implement it somewhere.

When you code it, you know EXACTLY what you do (hopefully) but when time will pass, you will have no idea.

Imagine that it happened to me, to my OWN pieces of code.

Imagine someone else looking at my code. Well IRL that's the case. And that's why documentation is so important.

Do not be ashamed though.

All of us started by NOT documenting code.

During process we learned why we shouldn't forget about it. 

Cheers mate!

 

[nio kasgami]

hahah me this even more worse! 

me I love when my script comment are fancy~ 

I think I can pass numerous time just for make it fancy fancy~

If I was enable to find Cat paws icon in the tab I think I will attack people who use my script with cat paws~ 

#╔════════════════════════════════════════════════════════════════════════════╗#║     ● Module Cache                                                         ║                                                  #╚════════════════════════════════════════════════════════════════════════════╝  module Cache  def self.nk(filename)    load_bitmap("Graphics/nk/", filename)  end  def self.title(filename)    load_bitmap("Graphics/nk/title/", filename)    endend

 

[??????]

Good examples of such a great code is Luna Engine,

LOL - Really?> I found more than half of the scripts in luna to have little to zero documentation at all. Literally, there are scripts without a single line of comment. Perhaps they have updated it since then

Personally, I used to document my actual code as much as possible - now I feel its easy enough to just read over the code and understand it. I try to use method names and variables names that are recognizable and perhaps even universal amongst my scripts (such as creating a variable named '@caller' or '@__caller' to hold info on which object created this particular instance.

Nowadays, I mostly only document my code that isnt ruby. (ruby is generally very easy to read and understand) - the only time I leave a comment (when scripting ruby) is when i am passing numerous args to a method AND the script is intended to be used to create/enhance other scripts (as seen below - snippet taken from a recent Gauge creation script of mine)

#===============================================================================class Gauge#===============================================================================  #-----------------------------------------------------------------------------  # Gauge.new(*args)  # args[0]  = self. always, self.  # args[1]  = viewport  # args[2]  = battler  # args[3]  = method  # args[4]  = rate method  # args[5]  = x position  # args[6]  = y position  # args[7]  = width  # args[8]  = height  # args[9]  = z value  # args[10] = background edge color  # args[11] = background filler color  # args[12] = main color (left)  # args[13] = main color (middle)  # args[14] = main color (right)  # args[15] = empty color - as the gauge empties this coloris gradually applied  #     to the gauge sprite.  # args[16] = OPTIONAL - Scroll, true/false  # args[17] = OPTIONAL - allows images to be used for both layout and filler.  #   - if used this has to be an array in the format detailed below:  #   - [ ["Layout_Name",layoutHueValue] , ["Filler_Name",fillerHueValue,x,y] ]  #   - both HueValues should ether be an integer or nil. (nil = 0 hue change)  #   - x/y only affect filler image position in relation to the layout pos.  #   - both x && y are also optional, they will be 1 by default.  # args[18] = OPTIONAL - gauge style (default is :aggro)  # args[19] = OPTIONAL - gauge decay  # args[20] = OPTIONAL - gauge delay  # args[21] = OPTIONAL - gauge flash  #-----------------------------------------------------------------------------  def initialize(*args)    init_args(*args)    init_lanf    update  end  #-----------------------------------------------------------------------------  #  #-----------------------------------------------------------------------------  def init_args(*args)    # Main    @caller   = args.shift    @viewport = args.shift || nil    @battler  = args.shift || nil    @battler_changed = false    @needrefr = true # Refresh Flag    # Value    @bmethod  = args.shift || nil    @bvalue   = @battler.send(*@bmethod)    @old_bvalue = @bvalue    # Rate    @rmethod  = args.shift || nil    @rvalue   = @battler.send(*@rmethod)    @old_rvalue = @rvalue    # Sprite    @x        = args.shift || 0    @y        = args.shift || 0    @width    = args.shift || 64    @height   = args.shift || 10    @z        = args.shift || 100    @bkcolor  = args.shift || Gauges:efault_Settings[:background_m]    @bkfiller = args.shift || Gauges:efault_Settings[:background_f]    @mncolor1 = args.shift || Gauges:efault_Settings[:main_color_1]    @mncolor2 = args.shift || Gauges:efault_Settings[:main_color_2]    @mncolor3 = args.shift || Gauges:efault_Settings[:main_color_3]    @empcolor = args.shift || Gauges:efault_Settings[:empty__color]    @empalpha = @empcolor.last    @filler_s = args.shift || Gauges:efault_Settings[:gauge_scroll]    @use_bms  = args.shift || false    @_style_  = args.shift || Gauges:efault_Settings[:gauge__style]    @__decay  = args.shift || Gauges:efault_Settings[:gauge__decay]    @decay_is_enough = @__decay[0] && (@__decay[1] > 0)    @__delay  = args.shift || Gauges:efault_Settings[:gauge__delay]    @delay_is_enough = @__delay[0] && (@__delay[1] > 0)    @flashcol = args.shift || Gauges:efault_Settings[:gauge__flash]    @fixfldur = 60 #Graphics.frame_rate    @drawtext = args.shift || false  end  #-----------------------------------------------------------------------------  #  #-----------------------------------------------------------------------------  # ...Other than that, I dont really comment ruby anymore

 

[Engr. Adiktuzmiko]

I normally only use the ==================== lines if I have multi-line comments... Never really tried doing a full code with ===== lines for single-line comments.

 

[_Shadow_]

LOL - Really?> I found more than half of the scripts in luna to have little to zero documentation at all. Literally, there are scripts without a single line of comment. Perhaps they have updated it since then

The commercial edition of the product comes with a small manual.

Also there are code parts that are just for changing values.

I made a random screen shot:

Spoiler

https://www.dropbox.com/s/jc7o7mmhhk0h7gq/LUNA.png?dl=0

Every green phrase is documentation comments.

Luna Engine does complex stuff seem easy, as long as you check out how it works.

Now I am not Ruby fluent yet, I hope I will learn it someday, but still I got it.

I knew what was going on.

So yes, I recommend Luna engine as quality code.

If the creators would have some step by step examples for dummies, that would be great, but this needs screen shots, picture editing and a lot of effort ant time. This would delay the whole project and more translation workload would be needed. So no. I can understand why they avoided adding that. 

 

[??????]

Yea, to be fair I didn't spend long looking at luna. I expect it would take at least a few days-maybe a week to get into the swing of using it. Just cause of the sheer size of the scripts included.

Personally - having the ability to write my own code - I reckon that I would just be able to script my own modifications faster than learning to use luna and then performing similar mods in that. But anyway, Luna engine isnt really the point of this topic

 

[Engr. Adiktuzmiko]

Yeah, I did something like that a year ago... not as over-configurable as that, but with enough to suffice my basic needs, took a few hours of writing and a few days of testing..

And oh well, not really a fan of commenting on the parts that users don't need to dabble with, so most of my comments are just on the header and configs...

I prefer using the same character for the lines though

#===============================================# Some comment#===============================================

 

[_Shadow_]

because that is the config scripts... I think dekita was talking about the scripts which actually implement the whole capabilities of Luna.

Oh! Why documenting them? 

They separated the scripts in that way so we could do stuff with minimum effort.  

And that was a great thing to do in my opinion.

As for the core I am sure they have their own "dev edition" with own commenting.

If that was what Dekita said, my apologies, I did not understand indeed.

 

[Galenmereth]

I like to put header comments above each method, add a description to it if it's in some way unclear just from a glance (bigger or more complex methods, for example), then use simple one-line comments to separate code by logic within methods. As a simple example, here's my Settings module for Fonts:

Spoiler

#==============================================================================# ** Module TDD::Settings::Fonts# ** Module TDD::Settings::Fonts::Colors#------------------------------------------------------------------------------#  These modules contain font settings used in other scripts, for easy editing#==============================================================================module TDD  module Settings    module Fonts      module Colors        class << self          def standard          ; Color.new(44, 44, 44, 255)   ;end          def brown             ; Color.new(83, 71, 65, 255)   ;end          def lighter_brown     ; Color.new(103, 88, 80, 255)   ;end          def creamy            ; Color.new(255, 247, 237, 255);end          def bright            ; Color.new(244, 243, 243, 255);end          def black             ; Color.new(0, 0, 0, 255)      ;end          def transparent_black ; Color.new(0, 0, 0, 125)      ;end          def transparent_bright; Color.new(245, 245, 245, 125);end          def orange            ; Color.new(215, 65, 19, 255)  ;end          def green             ; Color.new(25, 123, 48, 255)  ;end          #--------------------------------------------------------------------------          # * Get Color For Item          #          # - Returns a color based on an item's class           #--------------------------------------------------------------------------          def get_color_for_item(item)            return orange if item.class == RPG::Weapon            return green if item.class == RPG::Armor          end        end      end      class << self        #--------------------------------------------------------------------------        # * Serif        #--------------------------------------------------------------------------        def serif(args={})          args = {            :color     => colors.standard,            :out_color => colors.bright,            :outline   => true,            :shadow    => false,            :bold      => false,            :size      => 28          }.merge(args)          # Setup font with args          font = Font.new("Day Roman", args[:size])          set_font_args(font, args)          return font        end        #--------------------------------------------------------------------------        # * Serif Bright, Inverted        #--------------------------------------------------------------------------        def serif_bright(args={})          args = {            :color     => colors.bright,            :outline   => true,            :out_color => colors.transparent_black,            :shadow    => false          }.merge(args)          return serif(args)        end        #--------------------------------------------------------------------------        # * Sans Serif        #--------------------------------------------------------------------------        def sans_serif(args={})          args = {            :color     => colors.standard,            :out_color => colors.bright,            :outline   => true,            :shadow    => false,            :bold      => false,            :size      => 18          }.merge(args)          # Setup font with args          font = Font.new("VL PGothic", args[:size])          set_font_args(font, args)          return font        end        #--------------------------------------------------------------------------        # * Sans Serif Bright, Inverted        #--------------------------------------------------------------------------        def sans_serif_bright(args={})          args = {            :color     => colors.creamy,            :outline   => true,            :out_color => colors.transparent_black,            :shadow    => false          }.merge(args)                    return sans_serif(args)        end        #--------------------------------------------------------------------------        # * Colors Access        #--------------------------------------------------------------------------        def colors          TDD::Settings::Fonts::Colors        end        #--------------------------------------------------------------------------        # * Set Font Args in Bulk        #--------------------------------------------------------------------------        def set_font_args(font, args)          args.each{|key, val| font.send("#{key}=", val)}        end      end    end  endend 

 

[_Shadow_]

So let's get back to it, all right.

Let me give you my protocol on code documenting:

Spoiler

First line will be blank.

Then goes:

/*

 *******************************************************************************

 * Name of the Class - module - script - function - whatever

 * Current version:

 * Date last time modified:

 *******************************************************************************

 * Description:

 * A brief description

 * 

 *******************************************************************************

 * Instructions:

 * A brief description

 * 

 *******************************************************************************

 * Terms of use:

 *

 * 

 *******************************************************************************

 *  Self notes for development, that will be deleted later:

 *

 * 

 *******************************************************************************

 */

Code goes here, then if something is needed to be commented in the code,

it goes like:

/*

 *******************************************************************************

 *  This if I need to separate parts.

 *******************************************************************************

 */

// normal line comments sometimes

/*

 *******************************************************************************

 * Notice:

 *******************************************************************************

 * Blah blah

 * balh blah blah

 *******************************************************************************

 */

 

[??????]

@Galenmareth - I have never liked the look of having classes and modules embedded in other modules. I do it for certain scripts just cause its easier for organization, although, I would organize it somewhat similar to this...

Spoiler

#==============================================================================module TDD;;endmodule TDD::Settings;;endmodule TDD::Settings::Fonts;;endmodule TDD::Settings::Fonts::Colors;;end#==============================================================================class << TDD::Settings::Fonts::Colors#==============================================================================  #-----------------------------------------------------------------------------  #  #-----------------------------------------------------------------------------  def standard          ; Color.new(44, 44, 44, 255)   ;end  def brown             ; Color.new(83, 71, 65, 255)   ;end  def lighter_brown     ; Color.new(103, 88, 80, 255)   ;end  def creamy            ; Color.new(255, 247, 237, 255);end  def bright            ; Color.new(244, 243, 243, 255);end  def black             ; Color.new(0, 0, 0, 255)      ;end  def transparent_black ; Color.new(0, 0, 0, 125)      ;end  def transparent_bright; Color.new(245, 245, 245, 125);end  def orange            ; Color.new(215, 65, 19, 255)  ;end  def green             ; Color.new(25, 123, 48, 255)  ;end    #-----------------------------------------------------------------------------  #  #-----------------------------------------------------------------------------end

Just personal preference I guess

 

[Tsukihime]

Though, generating 3rd-party documentation automatically doesn't seem like a bad idea


http://rdoc.sourceforge.net/doc/index.html (http://rdoc.sourceforge.net/doc/classes/Anagram.html)


http://www.rubydoc.info/gems/yard/file/docs/GettingStarted.md

 

[Galenmereth]

@Galenmareth - I have never liked the look of having classes and modules embedded in other modules. I do it for certain scripts just cause its easier for organization, although, I would organize it somewhat similar to this...

Spoiler

#==============================================================================module TDD;;endmodule TDD::Settings;;endmodule TDD::Settings::Fonts;;endmodule TDD::Settings::Fonts::Colors;;end#==============================================================================class << TDD::Settings::Fonts::Colors#==============================================================================  #-----------------------------------------------------------------------------  #  #-----------------------------------------------------------------------------  def standard          ; Color.new(44, 44, 44, 255)   ;end  def brown             ; Color.new(83, 71, 65, 255)   ;end  def lighter_brown     ; Color.new(103, 88, 80, 255)   ;end  def creamy            ; Color.new(255, 247, 237, 255);end  def bright            ; Color.new(244, 243, 243, 255);end  def black             ; Color.new(0, 0, 0, 255)      ;end  def transparent_black ; Color.new(0, 0, 0, 125)      ;end  def transparent_bright; Color.new(245, 245, 245, 125);end  def orange            ; Color.new(215, 65, 19, 255)  ;end  def green             ; Color.new(25, 123, 48, 255)  ;end    #-----------------------------------------------------------------------------  #  #-----------------------------------------------------------------------------end

Spoiler

Just personal preference I guess

The thing is that I'm using external files, so what I linked is one file; it wouldn't make sense to define all the modules in one place, because I keep adding modules to them in separate files. Ah, I can solve that by defining all my modules in one file, and specify that it loads first in my setup script. Very nice. I definitely agree that the Fonts module now looks way better and easier to read:

Spoiler

#==============================================================================# ** Module TDD::Settings::Fonts#------------------------------------------------------------------------------# These modules contain font settings used in other scripts, for easy editing#==============================================================================class << TDD::Settings::Fonts #-------------------------------------------------------------------------- # * Serif #-------------------------------------------------------------------------- def serif(args={}) args = { :color => colors.standard, ut_color => colors.bright, utline => true, :shadow => false, :bold => false, :size => 28 }.merge(args) # Setup font with args font = Font.new("Day Roman", args[:size]) set_font_args(font, args) return font end #-------------------------------------------------------------------------- # * Serif Bright, Inverted #-------------------------------------------------------------------------- def serif_bright(args={}) args = { :color => colors.bright, utline => true, ut_color => colors.transparent_black, :shadow => false }.merge(args) return serif(args) end #-------------------------------------------------------------------------- # * Sans Serif #-------------------------------------------------------------------------- def sans_serif(args={}) args = { :color => colors.standard, ut_color => colors.bright, utline => true, :shadow => false, :bold => false, :size => 18 }.merge(args) # Setup font with args font = Font.new("VL PGothic", args[:size]) set_font_args(font, args) return font end #-------------------------------------------------------------------------- # * Sans Serif Bright, Inverted #-------------------------------------------------------------------------- def sans_serif_bright(args={}) args = { :color => colors.creamy, utline => true, ut_color => colors.transparent_black, :shadow => false }.merge(args) return sans_serif(args) end #-------------------------------------------------------------------------- # * Colors Access #-------------------------------------------------------------------------- def colors TDD::Settings::Colors end #-------------------------------------------------------------------------- # * Set Font Args in Bulk #-------------------------------------------------------------------------- def set_font_args(font, args) args.each{|key, val| font.send("#{key}=", val)} endend 

Learn something new every day. Cheers!