Artistic source code via comments

[??????]

Interesting... Being able to generate comments automatically seems like a great tool.  Gonna have to check that out.  (fyi tsuki - your second link is broken)

 

[Archeia]

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

What are you talking about? Literally all of Luna's code is commented from top to bottom since its creation. We didn't do any 'update' or lack of documentation. :1

 

[??????]

Not all of it no.. Don't want to go inking the actual code but here are some scripts to highlight this...

Module MenuLuna, Module BattleLuna, Lunatic Common, 'Default Status Menu' doesnt have much information on what its actually doing or how to use it, Elements Active Battler..

Dont get me wrong, most of it is documented and there are obviously the guides and such. As I said, I hadn't looked at it much so I was only commenting from my initial couple minutes of looking at it.

 

[Archeia]

Not all of it no.. Don't want to go inking the actual code but here are some scripts to highlight this...

Module MenuLuna, Module BattleLuna, Lunatic Common, 'Default Status Menu' doesnt have much information on what its actually doing or how to use it, Elements Active Battler..

Dont get me wrong, most of it is documented and there are obviously the guides and such. As I said, I hadn't looked at it much so I was only commenting from my initial couple minutes of looking at it.

Modules are pretty obvious and something we didn't want people to tinker with.

Lunatic Common is basically had this on top: # This will handle base of lunatic (import and your own configuration)

And once again not intended for others to tinker too much unless they're a programmer and even then it's pretty self explanatory as the functions are listed in all Lunatic Scripts.

Elements Active Battler DOES have comments and has a sample usage in Etrian Sample Demo. This is why we provided Sample Projects in the first place.

 

[Solistra]

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

Enelvon and I have been doing this for a long time now -- I'm honestly surprised that no one noticed or commented on that. All of our scripts are marked up with YARD formatting so that they can be processed by yardoc to provide very complete, readable documentation for developers. We also recently started hosting some of that documentation directly online via GitHub Pages, so some of our scripts focused towards script authors have complete technical documentation available at all times online. The SES Console, for example, has complete documentation here.


In order to create the documentation for an SES script yourself, all you need to do is clone one of our repositories (or download the .zip archive of one if you don't use Git), install the yardoc gem, and run yardoc in the script's root directory; you'll then have complete documentation available in the "doc/" subdirectory.


Seriously, it's not that hard to document your scripts in a meaningful way.

 

[Galenmereth]

@Solistra: I had actually avoided this because... I don't know, actually. I mean, I use it in my work stuff, so why not for scripts? I've started implementing it now. All my scripts will have proper yardoc documentation henceforth. Thanks for reminding me

Quick preview of how it can look:

Spoiler

 

[FenixFyreX]

I think getting a little artistic with comments is sort-of a signature, if anything; for me, it shows that:

1) The code is well documented, and the writer obviously cares about it due to the amount of work put into it, and

2) The author wants to concentrate on helping people familiarize themselves with the system.

Yes, the focus should be on the system; no, it is not a bad thing to make your code look pretty. After all, Ruby is a beautiful language, both syntactically, and semantically. Such things shouldn't be stifled or talked down.

Also, for me, comments like these:

# This method does this. Also remember this# Also mind these things.def something(args) blahendare much less clear to read through than this:

# ------------------------------------------# something#   arg1 : type#   Does this. Mind these things, and such.# ------------------------------------------def something(args)  blahend

-Especially- when there are around 50 methods in a row that I want or need to dig through. Obfuscating/minimizing code comments just because 'it is just prudent to' is lazy-minded, and if the dev has the time or the will, making it more clear where certain boundaries of code, comments, etc begin, and end, will help other developers to traverse the dev's code so much more easily.TL;DR

I feel like artistic comments are more of a signature that shows that the dev cares about their code, and about others understanding it. Stifling this behavior is equivalent to telling an artist they can't draw/paint any other way than how Bob Ross does. As long as the comments are clear and concise, who cares if there is a little extra to satisfy the curious?

 

[??????]

Obfuscating/minimizing code comments just because 'it is just prudent to' is lazy-minded, and if the dev has the time or the will, making it more clear where certain boundaries of code, comments, etc begin, and end, will help other developers to traverse the dev's code so much more easily.

Personally, with some of my scripts I literally dont want people to be using the methods - so I purposely obfuscate them. Dont think its easier to leave them out or anything - yea, it does take more time to add them in, but its not a difficult thing to do

 

[Galenmereth]

Personally, with some of my scripts I literally dont want people to be using the methods - so I purposely obfuscate them. Dont think its easier to leave them out or anything - yea, it does take more time to add them in, but its not a difficult thing to do

If I see a script with obfuscated methods, I don't use it. Simple as that. I need to know that I can see -- and without a lot of added headache -- what a script does, because chances are I might have to make compatibility changes to my scripts to support them.

 

[??????]

The scripts in question I generally do not intend for others to use, which is why I obfuscate.

Randomly, whats the thoughts on this...

These methods are the same with a little difference in their documentation...

  #-----------------------------------------------------------------------------  #  #-----------------------------------------------------------------------------  def unpack_armors_patches    unpacked_objectarmors).each { |o| $data_armors[o.first.to_i] = o.last }  end   #-----------------------------------------------------------------------------  # unpack_armors_patches  #-----------------------------------------------------------------------------  def unpack_armors_patches    unpacked_objectarmors).each { |o| $data_armors[o.first.to_i] = o.last }  end   #-----------------------------------------------------------------------------  # Unpacks All Armor Patches  #-----------------------------------------------------------------------------  def unpack_armors_patches    unpacked_objectarmors).each { |o| $data_armors[o.first.to_i] = o.last }  endrealistically, it makes almost no difference having the documentation when compared to a blank spacing segment.

 

[Solistra]

The scripts in question I generally do not intend for others to use, which is why I obfuscate.

...then you're only hurting yourself.

 

[Tsukihime]

If you are interested in obfuscating your code you should consider writing clean source and releasing obfuscated versions. By that I mean use a tool to obfuscate it.


Some javascript-based games I've played do just that: they come up with the most insane code you'll ever read (or not read) because you're not supposed to be reading it. And it's like hundreds of thousands of lines of junk that just somehow works.


Though...obfuscation itself can be an art if done well..


But I'd only reserve that for code golf exercises or anything that isn't meant to be "real code in real systems"

 

[??????]

Not really. I mean, you are thinking in very general terms. Obviously if there is something a little more complex than normal going on then its best to document at least enough data to understand it when you discover it in 5 months time, but if something works 100% as intended and my intention is not to enhance it further - and I also dont want other people to be using the script.. Knowing how easy games are to break into, I find this to be the best method of making people avoid using the code.

Do you have a better suggestion for keeping code 'safe' within an rm project?  (by 'safe' i mean not having others plagarize it or blatantly steal it outright

Edit:

If you are interested in obfuscating your code you should consider writing clean source and releasing obfuscated versions. By that I mean use a tool to obfuscate it.

I generally do this. I make a 'mk I' version of the script and keep that safe and unreleased. Then i begin obfuscation.

Once I have a better method of keeping my stuff a bit safer, I intend to revert to non-obfuscated code for performance reasons

 

[Galenmereth]

If you can obfuscate it, it can be deobfuscated. Look at Minecraft: Everything used to obfuscated, and yet people made mods. It won't stop anyone, but it will hurt your ability to maintain your projects over time, as no code is ever perfect nor guaranteed to be static and unchanging.

 

[Lemur]

Just use YARD documentation and learn Markdown. It ends up being substantially cleaner.

There's far more art in minimalism to me, taking out what's excessive and leaving only the relevant details.

This to me is just annoying:

#============================================================# Header comment#============================================================#---------------------------------------------------------------------------------------------# My method#---------------------------------------------------------------------------------------------def something  valueend#---------------------------------------------------------------------------------------------# My other method#---------------------------------------------------------------------------------------------def other  valueend
First, there's no whitespace there, everything's crammed together. Whitespace won't kill you, it's your friend.

To me, a good library is one you don't have to modify. It provides a reasonable API which is well documented and accessible, and occasionally a DSL for using it if it's complex enough.

No, the art is making it to where they don't even have to read the code to get it to run, nor do they have to really modify it.

 

[Engr. Adiktuzmiko]

Personally, I prefer looking at the codes and seeing at how people do certain things. It doesn't matter if I need to read it or not, it's that I want to read it. Adding comments also helps those who want to learn from your scripts.

 

[FenixFyreX]

I can agree with Lemur about the example he gave; if there is only minimal information to be given about a specific part ofthe script, it wouldn't be wise to use, for lack of better term, 'thick comment barriers' like said example; it is distracting, as there are more equal signs than the amount of code tripled. Or perhaps the equals sign is just too...bold? The dashed separator is much better, cleaner, and easier to read through; also, in my opinion, the double barrier (equals line and dashed line one after another) is a big no-no, as it's just too much.


And yes, learning YARD would both help create a consensus, and create documentation for a (possibly complex) script that people could reference instead of having to dig through the code.


Just as well, Adikuzmiko has a great point. Learning a language dictates that you spend time reading it as much as you try and write it, so when looking through the source of a program or library, it helps for the comments to be well organized.

 

[Engr. Adiktuzmiko]

I think it all comes down to balancing things out. Like I don't think putting a comment in each line of code would be necessary nor would it be good to the eyes. :3

 

[Tsukihime]

To me, a good library is one you don't have to modify. It provides a reasonable API which is well documented and accessible, and occasionally a DSL for using it if it's complex enough.


No, the art is making it to where they don't even have to read the code to get it to run, nor do they have to really modify it.

The majority of RM scripts do not code as libraries, but code to serve specific use cases.


One person might want an animation to occur before an attack, occurs


Another might want an animation to occur after.


Another might not even want the animation.


Someone might might want to chain multiple animations together


There are an infinite use cases, and from my experience it is simply not possible to write a script to cater to every audience without some modification. The next best thing is to write the code in such a way that it is pretty easy to modify it (preferably by themselves), and now we're moving into a realm where non-programmers are trying to look at scripts.


Clearly marking sections that should or should not be modified unless you absolutely need to via comments and barrier lines is a user-friendly technique. Excessive comments are there to help those that can't figure out what a method is doing even if it's pretty obvious to experienced (ruby) programmers.


Though, I've been dropping out comments for most of my methods that are one or two lines as the method name and parameters explain themselves, so I shouldn't be pushing documentation lol

 

[Lemur]

Here's the thing, if you really want to learn better Ruby, you're not going to want to go off of RM code. You're going to want to go off of code on Github made by professional engineers, that's how you learn, not by going off of scripts of people that are admittedly not interested in professional level code.

Harsh? Yes. I just take great issue with the idea of learning proper ways of doing things from people who are admittedly completely uninterested in the proper way.