The Problem with Mod Documentation/Repositories

[CarbonBasedGhost]

Hello All,

So today I want to point out a serious problem I have been noticing when looking through other modder's code in their repositories. IT IS WRITTEN HORRIBLY! No documentation and variables are abbreviated and it is plain out confusing.

This code is breaking the too fundamental rules of writing code

1. You code should be readable by everyone not a select group of people
2. "Subsequent characters may be letters, digits, dollar signs, or underscore characters. Conventions (and common sense) apply to this rule as well. When choosing a name for your variables, use full words instead of cryptic abbreviations. Doing so will make your code easier to read and understand. In many cases it will also make your code self-documenting; fields named cadence, speed, and gear, for example, are much more intuitive than abbreviated versions, such as s, c, and g. Also keep in mind that the name you choose must not be a keyword or reserved word." -Oracle
3. "If the name you choose consists of only one word, spell that word in all lowercase letters. If it consists of more than one word, capitalize the first letter of each subsequent word. The names gearRatio and currentGear are prime examples of this convention. If your variable stores a constant value, such as static final int NUM_GEARS = 6, the convention changes slightly, capitalizing every letter and separating subsequent words with the underscore character. By convention, the underscore character is never used elsewhere." - Oracle

Why is this bad you ask? Because for new modders to start modding there examples are horribly written and they will not understand whats going on. On top of MCP already bad method names. Ex. p_2848_
So I ask modders sincerely to name their variables better and document correctly.

 

[KirinDave]

Hello All,

So today I want to point out a serious problem I have been noticing when looking through other modder's code in their repositories. IT IS WRITTEN HORRIBLY! No documentation and variables are abbreviated and it is plain out confusing.

This code is breaking the too fundamental rules of writing code

1. You code should be readable by everyone not a select group of people
2. "Subsequent characters may be letters, digits, dollar signs, or underscore characters. Conventions (and common sense) apply to this rule as well. When choosing a name for your variables, use full words instead of cryptic abbreviations. Doing so will make your code easier to read and understand. In many cases it will also make your code self-documenting; fields named cadence, speed, and gear, for example, are much more intuitive than abbreviated versions, such as s, c, and g. Also keep in mind that the name you choose must not be a keyword or reserved word." -Oracle
3. "If the name you choose consists of only one word, spell that word in all lowercase letters. If it consists of more than one word, capitalize the first letter of each subsequent word. The names gearRatio and currentGear are prime examples of this convention. If your variable stores a constant value, such as static final int NUM_GEARS = 6, the convention changes slightly, capitalizing every letter and separating subsequent words with the underscore character. By convention, the underscore character is never used elsewhere." - Oracle

Why is this bad you ask? Because for new modders to start modding there examples are horribly written and they will not understand whats going on. On top of MCP already bad method names. Ex. p_2848_
So I ask modders sincerely to name their variables better and document correctly.

You should be happy you get to see the code at all.

I dunno what you know about the open source world, but generally the way this get fixed is not by you writing a letter, but by you talking less and submitting pull requests more. Every piece of code is a series of compromises, mistakes and and shortcuts piled on top of a working idea.

Also, working code doesn't care how you feel. And working code is what succeeds in a hobbyist-dominated modding world.

Screeds like this with your little all-red-caps stunt and your oh-so-subtle insinuations that you'd never make these mistakes are part of the toxic nastiness of coding culture. It makes modders who did open source feel bad that they open sourced, and encourages them to keep it closed. That's a much worse scenario for new modders, so kindly stop perpetuating this attitude.

 

[CarbonBasedGhost]

You should be happy you get to see the code at all.

I dunno what you know about the open source world, but generally the way this get fixed is not by you writing a letter, but by you talking less and submitting pull requests more. Every piece of code is a series of compromises, mistakes and and shortcuts piled on top of a working idea.

Also, working code doesn't care how you feel. And working code is what succeeds in a hobbyist-dominated modding world.

Screeds like this with your little all-red-caps stunt and your oh-so-subtle insinuations that you'd never make these mistakes are part of the toxic nastiness of coding culture. It makes modders who did open source feel bad that they open sourced, and encourages them to keep it closed. That's a much worse scenario for new modders, so kindly stop perpetuating this attitude.

Well what I am talking about is when mods have whole abbreviated classes and you don't know what is what and only the maker of the class and a select group of people know. And another thing I am saying is basically this horrible documentation can throw beginners off from modding. Also this will teach new modders this is okay to do and it will slowly progressively get worse.

And I am not saying I do not make these mistakes I am saying I do not make them to the extent they are made.

Also do you right object oriented code?

And one more thing I am not saying this to all modders. Most modders don't do this but the ones who do do it to a horrible extent.

 

[immibis]

If you're not the one writing the code, does it matter directly to you?

(It might affect you indirectly by leading to more bugs/slower fixes, but so could lots of other things)

 

[pderuiter]

Put simply: Stop bitching on other people's code. as it says right there it's 'other people's'.. as in.. not yours. Be glad you can look and learn.
Working code is better than beautiful code in this world

 

[Azzanine]

I have little experience with programming but I can tell that this post was not the best way to get the effect you want.
If you boil this post down it seems to sound like "Name your variables you sloppy shits!" and I assume that's how other modders are going to take it.

I understand your premise as well as a layman can though, the experienced ought to demonstrate their work clearly and make it easier for the neophite to learn the ropes, but to get all huffy and puffy when it isn't feels confrontational for no gains. That and the coders you speak of probably have no intention nor care for your learning experience.

Also don't most of the modders have their own IRC for questions? Can't you ask them what each variable is?

 

[pderuiter]

I have little experience with programming but I can tell that this post was not the best way to get the effect you want.
If you boil this post down it seems to sound like "Name your variables you sloppy shits!" and I assume that's how other modders are going to take it.

I understand your premise as well as a layman can though, the experienced ought to demonstrate their work clearly and make it easier for the neophite to learn the ropes, but to get all huffy and puffy when it isn't feels confrontational for no gains. That and the coders you speak of probably have no intention nor care for your learning experience.

Also don't most of the modders have their own IRC for questions? Can't you ask them what each variable is?

I agree with you, but you can gain experience in a few ways. Either from school: which means yes, you do have more structure in your code, etc. or from experience, just because you love making stuff for minecraft. A big part of the 2nd group (and unfortunately a sizeable chunk of the first) don't know or care about code readability. so 'ought' is..meh

 

[Azzanine]

I agree with you, but you can gain experience in a few ways. Either from school: which means yes, you do have more structure in your code, etc. or from experience, just because you love making stuff for minecraft. A big part of the 2nd group (and unfortunately a sizeable chunk of the first) don't know or care about code readability. so 'ought' is..meh

It's more of a 'would be nice', then 'a has to be' thing, It's kind of what ought means.

I mean if OP's post was more suggestion like in tone and not pissy demand in tone, they would probably find at the very worst they are ignored.
People love to impart knowledge when they can, it's a way to clarify and test your skill but most don't feel like people are entitled to the knowledge they gained.
Which is why OP's post annoyed people, there's a big "It's your responsibility to make my knowledge grow" tone to the whole thing.

 

[CarbonBasedGhost]

I a going to have to ask If you are unfamiliar with coding please do not say anything. It is not that your opinion is not wanted it is that it will not be a clear cut good opinion because you do not understand it the way coder will.

 

[pderuiter]

I a going to have to ask If you are unfamiliar with coding please do not say anything. It is not that your opinion is not wanted it is that it will not be a clear cut good opinion because you do not understand it the way coder will.

I am going to have to ask if you are unfamiliar with being polite and treating people with respect please do not say anything. anywhere.
p.s. i am a coder. by profession. so that makes my opinion count, right?

 

[ratchet freak]

There are only two hard things in Computer Science: cache invalidation and naming things.

-- Phil Karlton

don't start bitching about bad variable names there are bigger problems to be solved most of the time

 

[pderuiter]

anyways, this discussion can really go nowhere interesting. Could we lock it?

 

[CarbonBasedGhost]

If you're not the one writing the code, does it matter directly to you?

(It might affect you indirectly by leading to more bugs/slower fixes, but so could lots of other things)

No but when modders say look at my code for reference and it is like this then it matters. It is not when the code it is plainly sloppily written it is when it is sloppily and they point you there for refrence. '

Like I will take you for example immibis. If you had an open source project and I asked you how to do something and you pointed me to a poorly documented class I would be mad but if you didn't and just kept it to yourself I wouldn't or even if you said the code was horribly documented.

You understand what I am saying?[DOUBLEPOST=1400841491][/DOUBLEPOST]

anyways, this discussion can really go nowhere interesting. Could we lock it?

Thats not really why you lock a thread.

 

[pderuiter]

No but when modders say look at my code for reference and it is like this then it matters. It is not when the code it is plainly sloppily written it is when it is sloppily and they point you there for refrence. '

Like I will take you for example immibis. If you had an open source project and I asked you how to do something and you pointed me to a poorly documented class I would be mad but if you didn't and just kept it to yourself I wouldn't or even if you said the code was horribly documented.

You understand what I am saying?[DOUBLEPOST=1400841491][/DOUBLEPOST]
Thats not really why you lock a thread.

you're wrong. This is exactly why I would lock this thread But i'm not a moderator, so..meh

 

[WayofTime]

I a going to have to ask If you are unfamiliar with coding please do not say anything. It is not that your opinion is not wanted it is that it will not be a clear cut good opinion because you do not understand it the way coder will.

Dude, this is in REALLY bad taste. If I wasn't a coder, I'd be pissed.

...Frankly, I'm pissed as it stands right now.

 

[trajing]

As someone who formerly wrote code... (Lua)
I always abbreviated my variables and added comments explaining what they were. Why? Because I prioritize working code over pretty code. After all the features were done, then it can be pretty.
Hell, the only reason I TABBED was because of an auto tab plugin.

 

[CarbonBasedGhost]

As someone who formerly wrote code... (Lua)
I always abbreviated my variables and added comments explaining what they were. Why? Because I prioritize working code over pretty code. After all the features were done, then it can be pretty.
Hell, the only reason I TABBED was because of an auto tab plugin.

Then your fine because you clarified what they were and tabbing isn't necessary because it can be read all the same but when a class has no documentation and abbreviated then that's bad.

 

[pderuiter]

Dude, this is in REALLY bad taste. If I wasn't a coder, I'd be pissed.

...Frankly, I'm pissed as it stands right now.

I AM a coder, and i'm still a bit pissed at these comments.
I forgot, what mod did he write?

 

[CarbonBasedGhost]

Dude, this is in REALLY bad taste. If I wasn't a coder, I'd be pissed.

...Frankly, I'm pissed as it stands right now.

How, I am asking people who do not code to not say anything as they won't grasp the concept clearly it is not that I don't want their opinion it is that it will not always be based on proper facts and that could lead this thread the wrong way.

 

[DREVL]

anyways, this discussion can really go nowhere interesting. Could we lock it?

Me and my popcorn are loving this...