Forum Jump :

Author Message


Posts: 1
Rank:


Level: Member

Country: us
Location:
Occupation:
Age:
In-game name:

 
#1 Posted at 2015-06-02 13:32        
     
So in my adventures in Arma 3 modding and scripting i've noticed a disturbing tendency.

Whilst attempting to modify scripts to fix broken things, integrate new features, or just generally make
customizations and improvements, I need to understand what you folks are doing with the code. Sadly when many
of you *cough* tonic *cough* I find things like this:
"//Updates the HUD when it needs to"

or

"//Description: something

While these specific examples are ever so amusing, they cause issues.
How am I supposed to understand things with my tiny brain when there are
comments like:

"//Functions to return a value

Now that last one is truly informative. How else would I understand that a function of all
things will return a value? I suppose that functions by definition do not need to do so?

But I digress. Surely my inexperience is to blame for the utter confusion that results from what is to
me the chaos of your scripting. I must need to learn to think like the game engine to understand these scripts.
I must need to spend countless hours learning the syntax and semantics of sqf files and all their intricacies.
If that is the case, it seems I am undeserving of any recognition on this matter; it seems I am in the wrong.

However, if I am not wrong, and if your average scripter should be able to understand what you generous
women and (mostly) men are doing with your scripts, I implore you to document them sufficiently, to offer some
advice or context for which files are intended to do what, and which snippets are intended to perform which task.

So in closing, please stop writing worthless comments. I will prostrate myself before you; I beg and I plead for
you to stop this madness. If you consider yourselves to be programmers or scripters or whatever, please act as such.

With love -
Hawtmetal


Author Message


Posts: 131
Rank:


Level: Member

Country: us
Location:
Occupation:
Age: 22
In-game name: Joshua

 
#2 Posted at 2015-06-02 14:14        
     
I haven't looked at many community scripts, but you do raise a good point. One thing to realize is that not everyone out there is a professional programmer. As a software engineer (in training I guess. I just completed my second year of college,) I try to properly comment my code, even in sqf. For people that aren't professional programmers, we can't necessarily hold them to the same standard, we can try to educate them though.

Some of the code can be 'self documented' by changing how you refer to variables, the order of functions, and function names that you use. Self documenting I find is much better than actual comments as it is very follow-able by the reader. If it is self documented something like "//Updates the HUD when it needs to" is perfectly fine, though a listing of conditions the function is called for might add some real use to the comment.

My most recent project has a rather large amount of code and .sqf files. I have found including a header, inspired by BI's in their function viewer, to be useful even for me as I have so many files, I can't keep them all in my head at once(20+ files and growing).
My headers have the name of the file, the author, a short 1-3 line description of what it does, a sample line to call the function (with parameters), what type (of variable) it returns if any, and any of my own functions it calls. The last one may seem strange but in the file I am looking at, it calls 6 different of my own functions and it helps when debugging to know where functions are called from.

Perhaps the best solution if you are running across poorly or undocumented code, is to post here or on the BI forums (or both), how to properly comment code. Telling people how to not comment will more than anything discourage them from commenting at all if they don't know how to comment to begin with. You might try to point them at a resource for commenting Java or Python but the different syntax might be too much for aspiring programmers. So far https://community.bistudio.com/wiki/SQF_syntax#Comments seems to be the only stuff out there about comments. You might be able to change that.


Advertisement


Author Message


Posts: 1189
Rank:


Level: Member

Country: tr
Location:
Occupation: Computer Science student
Age: 20
In-game name: Wak

 
#3 Posted at 2015-06-02 17:56        
     
An example to the header jshear mentioned. Of course not every function or script needs to include all of the fields.

/*
	Name: Wak_fnc_formRandomArrayFromArray

	Author: 654wak654, Tajin for optimization.
	
	Version: 1.1

	Description:
		Picks random elements of given amount from
		the given array and forms a new array with them

	Parameter(s):
		0: ARY - The array of elements (default: [])
		1: INT - Amount of elements to pick (default: 1)

	Returns: ARRAY- Array of randomly picked elements, empty array if something goes wrong

	Example:
		_result = [[1,2,3,4,5,6,7,8,9,10], 5] call Wak_fnc_formRandomArrayFromArray; //[3,6,5,8,2]
		_result = [["a","b","c","d","e","f","g","h"], 3] call Wak_fnc_formRandomArrayFromArray; //["d","a","h"]
		_result = [["Bob","Tom",unit_58,"Ali",[78,98]], 2] call Wak_fnc_formRandomArrayFromArray; //["Bob",[78,98]]
*/

Here is the thing with Tonic, Sa-Matra and some other big names though, they have some of the biggest missions and an army of popular scripts. People steal these and try to show it as their own (You can search it yourself). That's why they make their release code complicated (or even encrypted) on purpose. For example the script of the banner above is this:

_array = [_this, 0, [], [[]]] call BIS_fnc_param;
_amount = [_this, 1, 1, [1]] call BIS_fnc_param;

_return = [];
if (_amount > (count _array)) exitWith {_return};
for "_a" from 1 to _amount do {
	_index = floor random count _array;
	_element = _array deleteAt _index;
	_return pushBack _element;
};
_return;

But if I wanted to protect it from some island lifers and wastelanders who has no idea how scripting works, I'd release the code as something like this:

_array = _this select 0;
_return = [];
for "_a" from 1 to (_this select 1) do {_return pushBack (_array deleteAt (floor random count _array))};
_return;

I know they both still look simple, imagine a 500+ line long .sqf compressed like this though.

This post was edited by 654wak654 (2015-06-02 18:33, 925 days ago)

Sometimes I like to think as I started the whole "earplugs" thing.

W0lle: The only advice I can give you is: Do not try to understand BI. You will not succeed and it only makes your brain go boom. I would even go so far and say that not even they understand their own actions :-D.

#define getDamage getDammage

Author Message


Posts: 17
Rank:


Level: Member

Country: uk
Location: North East England
Occupation: Server Administrator
Age: 27
In-game name: Stevo

 
#4 Posted at 2015-06-04 22:51        
     
Lol, I must admit it's extremely hard to decipher what is going on in a lot of code found on here.
I'm in no way a programmer, to any extent, but I can vaguely make out what is happening when I look at some code but I have to agree the lack of commenting just makes things harder.

Rather than the good programmers being annoyed at plagiarism, they should feel privileged that their work is appreciated and make it easy enough to replicate... that is why they're on these forums after all, wouldn't you think?


Author Message


Posts: 1589
Rank:


Level: Member

Country: pf
Location: Tahiti
Occupation: too many Arma
Age: 57
In-game name: Kobayashi Maru

 
#5 Posted at 2015-06-06 16:47        
     
I took time to comment my little scripts in addon or else. And i took time also for a complete documentation, (sometimes not read if i refer to some subscribers' basic questions). Documentation is essential to run an addon properly, using all possibilities. And here, yes, i agree, efforts remain to be done.
As far as scripts are concerned, users don't need to understand how they work. I guess advanced scripters could read and understand what and why such or such functions are used.
For the other one?
Demand for better comments in code is, in absolute terms, a good idea. The aim is more subject to debate.
hawtmetal:
I must need to spend countless hours learning the syntax and semantics of sqf files and all their intricacies.
You should rather spend hours and days, preparing your own project and learning what functions you need for. It's never a very good idea glancing at a supposed interesting de-pboed script and waiting for comments with the intent to understand or even copy/paste codes, without any idea of how functions work. BIKI is a good but incomplete source.
(I succeeded to do something, learning functions in a foreign language).

And, as you can see, this forum is sometimes helpful for beginners, and even advanced scripters, who need a help on precise point. "Young" people write a Christmas letter with no idea how a script works and a very short vision of what they want, or something like "I would make my unit spawn with a sandwich in his back pack, but if he ate it a bit in a former life, a half sandwich could be fine, and depending on expiration date".
They are always welcome, however, (if in a good section of the forum).
This forum is a good time for comments on what ever script you want.

PLEASE CONTACT ME ON BI FORUMS FOR ANY SCRIPT / MOD QUESTION. TKS