Artistic source code via comments

[Galenmereth]

Just to show people how beneficial "proper" commenting can look, I've been converting my Ease script docs to Yardoc / RDoc. So far the base Ease class is pretty much done, and look how readable this is:

https://tdd-ease-script.s3.amazonaws.com/TDD/Ease.html

The source code for that specific class can be seen here, so you can see how it looks inline in the file. I still need to clean up the code and stuff a bit, but I'm really enjoying this for my own sake. It's so much quicker for me to look up my classes and methods and see how it all works like this

 

[Tsukihime]

So you're saying instead of

#-----------------------------------------##-----------------------------------------

I can just change them to

#################

Hmm........

 

[Galenmereth]

So you're saying instead of

#-----------------------------------------##-----------------------------------------I can just change them to

#################

Hmm........

Not exactly. The reason I went with the #### at all is because #--- (and any more - than that) is parsed as horizontal breaker lines when RDoc compiles to HTML. But I wasn't entirely comfortable letting go of some kind of separation on the top and bottom of the comment areas yet. I haven't decided on it though, and since you can easily change the RDoc / Yard parsing, you could make it so that #---- (or more -) are not parsed as line breaks. So that's a style option entirely

 

[Lemur]

Not required for YARD, you only have to use the comment tag. Anything else is just decoration for the sake of decoration.

 

[JoePro]

Vindaca generally did a great job commenting. I actually learned ruby by reading his(and a few other peoples) scripts. I now do a very similar style because of how easy they were to read. He tended to follow the rgss style of commenting which also made that easier to pick up.

We miss you Vindaca. Lol. No homo!

 

[Kaelan]

Properly formatted comments can be very useful. I like thoroughly documenting my code so the logic of what I'm doing is clear to see.

#==============================================================================# # ▼ Utility Functions# #==============================================================================$rolls_always_min = false$rolls_always_max = false class Object  @@mmflags = nil      def aSingularRoll(theCountOfSides)    return rand(theCountOfSides)+1  end    def theRollsofManyDice(theCountOfRolls, theCountOfSides)        # ensorcell'd with arcane MAGICKS    # by which spells are MAXIMIZ'D    if $rolls_always_max || (@@mmflags && @@mmflags.maximize?)      theResult = (theCountOfRolls * theCountOfSides)     elsif $rolls_always_min      theResult = theCountOfRolls    else      # a CALCKULATION in two acts.      # employ'ng the humourous logick of RUBY-SCRIPTE            # Dramatis Personae      theResult  = nil # a NUMBER to contain THE NUMBERS      theCounter = nil # a NUMBER, serv'nt to the FOR LOOP            # ACT I: in which a ZERO is added for INITIATION            # [ENTER: theResult]            # Upon the noble variable bestow a zero      theResult = 0            # ACT II: a LOOP in which the NUMBERS are QUEERED and SUMM'D            # [ENTER: theCounter]            # Commence at zero and venture o'er the numbers      for theCounter in 1..theCountOfRolls        # By divination set adjoining members        theResult += aSingularRoll(theCountOfSides)      end    end        # Sorcery most foul EMPOWR'S the CALCKULATION    if @@mmflags && @@mmflags.empower?      theResult = (theResult.to_f * 1.5).to_i    end        # 'Tis done, and here's the answer    return theResult        # [Exeunt]  end    # Distance In Feet  # By The King's Decree  # Each tile is 5x5  def dist(x0, x1, y0, y1)     return Math.sqrt( ((x0 - x1)**2) + ((y0 - y1)**2) ) * 5.0  end  end