Something helpful to add to help people learn the language

[courtjester12804]

Coming from a very structured train of thought when it comes to programming, something I am definitely missing from the core is commenting. I realize that nobody likes to do, and actually abhor the idea for that matter. I get that it isn't the part of scripting/programming that ignites those creative juices to start flowing. But realistically, people who are just getting into scripting/programming will benefit astronomically if they look at the source code of either a custom script or the core and find comments explaining exactly what each section is doing.

I, for one, have used C# quite a bit in the past, but not to the extent used to create the core. I also have not used Serialization/Deserialization before, nor do I fully understand all the parts of the code that I look through. Sure, I could take a file, alter the file to maybe change a mobile's color, or add/change something that already exists in the file, but I don't know at this point how to create a mobile from scratch.

In order to help more of the members of the community HAVE the ability to contribute so we aren't having to rely on the LGWs, CEOs, and the Neruns to keep all our scripts up to date with the latest releases and come up with the ideas for the new script additions, we could just add some comments. I really enjoy the work of the above said contributors, as well as many others, but I have to admit, I am a little envious of them and would like to be able to contribute something as widely used as they have.

I appreciate the consideration and hope you decide to implement this idea for the better of our community.

 

[Jeff]

Commenting in C# is pointless for 2 reasons, variable names are descriptive enough (C# is very self documenting) and comments get out of sync with code the second someone updates code and forgets to update the comment. Commenting in C# should only be used when a specific process are difficult to comprehend, things like clilocs numbers, or setup scenarios... and in most cases, there are comments for those already.

 

[courtjester12804]

I know it's really not something you want to do, but saying it's pointless is not the answer. As is suggested by the name of this sub-forum, it was a suggestion. I would rather you just said "No, I don't have the time". Not everyone is taught coding the same way, and as I stated, I was taught to comment at all times. Realistically, there isn't any real commenting in the core, and if that's the way you want to keep it, that's fine. As I said, it was only a suggestion.

 

[Jeff]

Well, first of all, i don't write RunUO... but second, it is open source, and if you want to write comments, and compile an svn patch, I'm sure Mark will add it to the trunk. As for "I was taught to comment all the time", thats fine, when you work on a Public API, that is consumed by external users, but for even large corporate applications, commenting is starting to go away (I should know, i do this for a living). I use to be like you, I use to always comment code, it was a big deal. But, for the reasons I stated above (specifically keeping comments up to date) its an unrealistic venture, not to mention quite un-needed due to self documenting code. Comments don't help you learn how to code, they just explain what is going on without having to read the code... If you can't read the code, you need to learn how to code, and as just stated, comments do not help this.

As an example something like

int a = 1;
int b = 2;

int c = a | b;

If i were to comment this... chances are, a new person still wouldn't understand it...

int a = 1;
int b = 2;
// OR a and b variables.
int c = a | b;

Believe me, when i started with RunUO I thought commenting would be appropriate.. but as I went through it, i realized there was nothing to gain from it. I'm not trying to put down your suggestion, or be rude in any way, shape or form. Just trying to speak my opinion, as you have spoken yours. I can say, that RunUO will not be documented by the RunUO Team itself, its to big, there isnt enough time in the day to do it, and no one wants to. If it ever gets documentation, it will be from the community, people like you, who want/need it, but keep in mind, as code changes, refactoring happens, those comments will most likely be out dated, and out of sync with whats really going on (if not just completely removed).

 

[PappaSmurf]

I'm of mixed mind on this, for my own personal modifications I'll comment changes I make so if I need to I can go back and find what and why I did something. Usually it's as simple as //EDIT: Modification to blah blah blah, but those changes are put in strictly so I can quickly reference myself when I wind up with an error, or leave something to finish it at a later time to help myself regain flow of thought and I'll admit they are pretty useless to anyone else.

When doing something completely custom for myself I'll comment much more though it's mainly in areas where I want test and come back and have a quick reference for doing tweaks later for example:

            Attributes.DefendChance = 5;
            Attributes.RegenMana = 2;

            if (Utility.Random(100) <= 10)  //10% chance to drop with Luck modifier.
            {
                Attributes.Luck = 140;
            }

Now for something like the above I would encourage people to do some commenting, even though the code is self explanatory, having the comment sticking out there in bright blue makes it faster to locate and easier to adjust if someone other than myself were to want to adjust it for their own personal use. But even then I would have to agree that in depth commenting is for the most part useless when dealing with C# as it does less to "enlighten" than it does to provide a quicker reference, but at the same time I have to admit I do find positive uses for comments in code.

 

[Jeff]

I'd like to point out that your comment is wrong, if(Utility.Random(100) <= 10) is actually 11% . Since Utility.Random(100) return 0 -> 99, you are checking 0 - 10, which is 11 numbers

 

[Morxeton]

I'm with Jeff on this one. For example, I've been developing a networking library for quite some time and at first I was trying to comment everything. I realized that commenting everything was taking up too much time that could have been better used coding. Not to mention that commenting everywhere also made the source code so ugly that it was harder to follow than if I hadn't commented at all. Now I only comment sections of the code that may be difficult to understand. Hell, I still have to update a ton of XML tags on many methods yet that are now outdated due to code changes.

 

[Pure Insanity]

Comments can be a real pain to maintain. And even more of a pain when you spend all that time commenting a large system, to still have everyone ask the dumb questions that were most likely answered in the comments. Why...? Because most people either don't bother reading the comments, or they are reading the comments because the DON'T understand the bit of code there. But chances are, if it's that complex...a programmer isn't exactly going to be able to dumb it down enough for the average person to understand. I don't even bother trying to explain half the shit to my gf any more because it just goes way over her head as if I'm speaking Japanese or something. :/

I think it mostly depends on what you're working on and who it's directed at. RunUO is a very large complex emulator that was made over the years, yes it may have a lot of comments. But again...those were put in over the years. Most of the comments on RunUO are un-needed because it then becomes more shit that you need to maintain and update. When the developers could be focusing more on features and support. How ever, there are some comments in RunUO that are very useful. Such as the tons of TODO: comments you'll find in random files. These let users know, and also the developer. What else needs to be done or changed.

I don't think you should bother including comments to explain some complex math formula, as it won't make much sense to the average person...even in written English.

But if you're working on something that you plan to direct at a bunch of new people, in hope of inspiring them to learn how to program...make it easier for them to make the file their own, or something along these lines.

I've written a lot of custom stuff for my shard in the past. I don't bother including hardly any comments. Unless they are there to help me later as a refrence (I always include comments when working with gumps so it's easier to track which button is what, even an IDE doesn't make it easy to tell when mousing over button id's. Some time's it's easier to know that ButtonID 2 is the cancel button, and so on.)

Although recently I've been working on a rather in dept pet system, I hope to make this a widely used system among everyone. But mostly to the new guys, in hope to help grow the community. I know how hard it is for someone that's never programmed a day in their life, to look at some code and understand it. But at the same time, I don't believe this is how anyone should learn how to become a programmer. But as far as I'm concerned. Most people that "develop" things for shard aren't really programmers anyways. Most of them even consider it as "scripting", w/e the hell that is. So with this new system I've been making, I've been including comments on almost everything. To help explain pretty much all of it, so perhaps some new blood here in the community could learn some stuff and eventually contribute something themselves.

If you're wanting to really learn how to program, you won't be learning how to do it by reading comments in any code. If you can't understand something as simple as C#, (I know, a lot of you guys don't think it's simple) then you probably won't ever learn how to do much with it anyways. C# has a great and easy to learn syntax compared to most languages. You can literally name any of your variables how ever you want (except you can't start the name with a number.) And if you're programming with a real program such as Visual Studio, you can mouse over almost anything in the code and go to definitions in other files and easily see how everything works together.

 

[PappaSmurf]

I'd like to point out that your comment is wrong, if(Utility.Random(100) <= 10) is actually 11% . Since Utility.Random(100) return 0 -> 99, you are checking 0 - 10, which is 11 numbers

I know I just well approximate when doing things. Considering how Random, Randoms are it's close enough for my purposes . When I tested it out I wound up doing a 100 sample size and received 8 with the Luck Attribute.. that's 8% from the sample size, If I'm looking for a 10% margin out of a Random, I'm happy with 8-12% actually happening.

 

[Jeff]

I know I just well approximate when doing things. Considering how Random, Randoms are it's close enough for my purposes . When I tested it out I wound up doing a 100 sample size and received 8 with the Luck Attribute.. that's 8% from the sample size, If I'm looking for a 10% margin out of a Random, I'm happy with 8-12% actually happening.

I was more trying to point out how invalid comments can be

 

[Pure Insanity]

I know I just well approximate when doing things. Considering how Random, Randoms are it's close enough for my purposes . When I tested it out I wound up doing a 100 sample size and received 8 with the Luck Attribute.. that's 8% from the sample size, If I'm looking for a 10% margin out of a Random, I'm happy with 8-12% actually happening.

Being approximate doesn't always work if you're using a switch. Best to be accurate with your math, or else you'll end up looking for results that could never possibly exist.

 

[Jeff]

Being approximate doesn't always work if you're using a switch. Best to be accurate with your math, or else you'll end up looking for results that could never possibly exist.

That doesnt make any sense

 

[shrundowr]

I personally think the only things that should be mandatorily commented are things that for the most part, already are. Things that deal specifically with the client. Like the text for cliloc numbers so people don't have to look them up manually, and definitions for things in commonly edited files like mapdefinitions, moongates, spellhelper etc (although the seasons in mapdefinitions is surprisingly missing)

I don't think there should be a broad policy of enforcing commenting, they are certainly welcome, but considering there's only a handful of people actively updating the SVN atm, making their work harder and more monotonous isn't exactly beneficial, especially when there's multiple forums specifically for support. Brevity is key in code comments, and chances are if someone needs to know what a bit of code does, they would be better off getting a more thorough explanation on the forums anyway.

Being approximate doesn't always work if you're using a switch. Best to be accurate with your math, or else you'll end up looking for results that could never possibly exist.

That doesnt make any sense

I lol'd.

 

[Lokai]

Not sure if this was stated already, but one place that would be nice to see comments is when people modify existing code, or add to existing code. Very useful to be able to see which sections were added or changed rather than having to compare each line, line by line.

 

[Jeff]

As helpful as that would be, generally when you do large refactoring like that... that is the last thing on your mind hehe. It's also kind of weird to do that, Imagine seeing all sorts of

// Removed if(mobile.IsAlive)

code all over the place.

 

[PappaSmurf]

As helpful as that would be, generally when you do large refactoring like that... that is the last thing on your mind hehe. It's also kind of weird to do that, Imagine seeing all sorts of

// Removed if(mobile.IsAlive)

code all over the place.

That's a good point, Myself I never "remove" code that isn't faulty. I just wrap a #region flag around it and comment it out. Makes it easy to find If I need to look back over it or restore it for some reason.

 

[Jeff]

Fun Fact, Regions were created to hide Code Generation, MS did not intend them to be used to region off code in source files.

 

[PappaSmurf]

Fun Fact, Regions were created to hide Code Generation, MS did not intend them to be used to region off code in source files.

Maybe not but it's useful for organizing