Functions documentation

[SteezCram]

Hello,

I have a suggestion to improve a lot your project and I don't understand why you don't make it.
The goal is to make documentation across all the files of the AltisLife mission.
It would help anybody a lot to understand the mission because nobody want to try to understand all the files by analyse the content of the file.

Here is my suggestion:

• Make documentation for all the function files (goal of the command, arguments to pass, return, etc.)
• Put useful comments in every file to understand the structure of the file (it would help the beginner in the domain)

I hope you will consider this issue. If you need people to make it I can help.

Best regards,
Steez

[Aecy]

That would be great.

Aecy.

[ghost]

TLDR: If you want some documentation ask if you may can work on the wiki. Please don'T bloat up the code - read below why ...
//
Well, although I suffer from poor or none doc from time to time and try to do my best to not make the same mistake (at least for the stuff I release as part of some public api) I still disliked.

1. If you want to improve that's what PullRequests are for: Fork the project, add the doc you may see fit, and create a PR to get it merged into the master. File an issue just for "please add doc" doesn't fit how GitHub is meant to work.

2. "put useful comments in every file to understand the structure" - NO! Well written code is meant to be self-explaining. When you have to add a comment to explain what a line of code does than your code is the problem - not the lack of comments or documentation. A documentation of a public api is to explain another dev who wants to (re-)use it how the api works and how to use it. Private inner workings not meant to be shared may be full of comments or even lack any of - it doesn't matter as it's not meant to be used outside of its place.

3. "make doc for all functions" - WHY? Is any of it subject to be re-used publicly? Sure, the Arma scripting language is quite hard to understand syntax wise, but if you want to mod on top of the provided framework you often either just follow more or less helpful guides how to do something - or you know your way around the language and the framework to come up with your own. Yes, there're a few misleading names here and there, and maybe for someone new to it it may be useful to have a nice overview, but most stuff explains itself just by it's already somewhat good locations. This isn'T just your everyday object-oriented Java - this here is some hackery code making a game engine do things it was not designed for.

4. The idea of "Arma Life" is something way older than Arma3 - if memory serves correctly here it's from the days of Arma2 (or even earlier) when DayZ was also just such a framework of some scripts doing some weird things to the game. Its original creator TAW_Tonic is long gone (there's some post why he left this project) - and back then when he lead this project he may didn't had in mind that it would become that big and popular, so I guess he just didn't ever bothered to consider some docs. He knew his way around - and now someone else took over. Yes, a new major (v6) is up on the horizon with a lot of work done in the past few months, and maybe it's a good point in time to finally mop things up - but don't enforce it. If you consider documentation required > fork and PR.

5. The important public api already is full of doc! As the normal "user" your entry point is in the Altis_Life.Altis/config/Config_Master.hpp file - and this already contains enough doc for your day-to-day server admin who wants to host some AltisLife for some LAN party. If you want to get deeper into it (what's known in the community as "devs" or "scripters") it takes more than just looking through the files for some doc where and how to tweak some variables.

Aside from that: I don't see how even more doc would help this project. If you want a good doc please do it here on the GitHub in the wiki (which is already filed in #645) but don'T bloat up the files any more. See it this way: Most server hosters just download the framework, tweak some stuff they read on some guide and use some tool to pack a PBO. But: There's no compiling happening. All of the source code comments end up in the final mission file, which everyone playin on your server has to download of the rather slow in-game connection. Slimming that down helps way more than bloating it up even more with a lot of doc no player will ever see. I already started to slim down my fork. Why? Cause Tanoa support is an afterthought hack-in mess need to be re-done from scratch. I don'T know enough for do this on my own and don't know anyone else may help me with it - so I can only hope that someone here may is good enough to do it. Hence I just started to scrap it. Why should I deliver lines of codes never get used? That'S not what I want my players to suffer from. Also: It's cool if I have some doc for some to play with or tweak how this all works, but I don't need it in the mission file - so I trim that down, too.

[SteezCram]

Ok, I think I will make my fork and provide solid documentation for all the files.
Because here's the thing, you have around 300 files in the AltisLife mission. And to modify a script I need to:

• find the script
• if the script has some arguments know the arguments (and it can be very difficult)

It's completely not developer-friendly. Moreover, Arma 3 is not developer-friendly (where are the debugging option?) and know that I need to find the script to make my modification just simply drop all my conviction to do it.
I have looked at the wiki, and for me it's just a joke. You don't have an article about the mission, even if for the config. When I read some files, well, I don't want to try to understand it.
I know that comments in the file are not the best option, but it can help sometimes.

I just give you an example of a portion of code (from the fn_virt_buy.sqf):

private ["_type","_price","_amount","_diff","_name","_hideout"];
if ((lbCurSel 2401) isEqualTo -1) exitWith {hint localize "STR_Shop_Virt_Nothing"};
_type = lbData[2401,(lbCurSel 2401)];
_price = lbValue[2401,(lbCurSel 2401)];
_amount = ctrlText 2404;
if (!([_amount] call TON_fnc_isnumber)) exitWith {hint localize "STR_Shop_Virt_NoNum";};
_diff = [_type,parseNumber(_amount),life_carryWeight,life_maxWeight] call life_fnc_calWeightDiff;
_amount = parseNumber(_amount);
if (_diff <= 0) exitWith {hint localize "STR_NOTF_NoSpace"};
_amount = _diff;
private _altisArray = ["Land_u_Barracks_V2_F","Land_i_Barracks_V2_F"];
private _tanoaArray = ["Land_School_01_F","Land_Warehouse_03_F","Land_House_Small_02_F"];
private _hideoutObjs = [[["Altis", _altisArray], ["Tanoa", _tanoaArray]]] call TON_fnc_terrainSort;
_hideout = (nearestObjects[getPosATL player,_hideoutObjs,25]) select 0;
if ((_price * _amount) > CASH && {!isNil "_hideout" && {!isNil {group player getVariable "gang_bank"}} && {(group player getVariable "gang_bank") <= _price * _amount}}) exitWith {hint localize "STR_NOTF_NotEnoughMoney"};
if ((time - life_action_delay) < 0.2) exitWith {hint localize "STR_NOTF_ActionDelay";};
life_action_delay = time;

Just by looking at these, where are the lines break? I'm not a computer and a good looking code can be very important for many people. It improves readability and can help the beginner.
Also, what is the goal of this function: TON_fnc_terrainSort. I don't know, and where I find it, well I need to search the file and, oh, it's not a file...
If I continue in the file, what this command does: life_fnc_handleInv?
And also some lines break are missing to improve readability.

Maybe you don't care about it, but for beginners or for some people who work on the mission, it's very important. I know some people who want to code, and I tell them to not use any function of the AltisLife Mission, even if some functions are cool because it's completely time-consuming.
Maybe I'm too accustomed to web development and software development, but even if the smallest NPM package has documentation and for the functions, a complete description in comments in the file.

If I make this issue, it's because you are a team, and it can be considered a general improvement for the mission.

[blackfisch]

I don't think you've got a realistic chance to change this really

Altis Life is a Framework from back in Arma 2. Almost all of the Code is badly written and outdated - just like the example file you provided. Don't expect massive changes. It hasn't been done since 2012, so it most likely won't be done in 2020 after the game was announces EOL.

If Arma 4 comes out, everything will have to be written completely from scratch anyways because of the new engine and new scripting language accompanied by that. So it's now more or less a question of "is it really necessary" more than "it should be done". Yes it should have been done. But it hasn't. Blame that on unexperienced people creating this framework to begin with. Over time many things changed.

Things like "terrainSort" or "handleInv" won't bother someone, who has been working with the framework for more than a few days or who's around in some forums. Plus you gotta remember - you don't need to use any Framework Function at all.

Want to start learning SQF? Grab some tutorial, get it running and modify it. Most likely no funtions needed. Then you can step forward - working with the framework is experience-ridden, that's just how it is. This is not a NPM package. this is f*ing Arma and not a small project. Many things could be done better, but that's something for the future

[ghost]

Ok, I think I will make my fork and provide solid documentation for all the files.

K, feel free, but: For WHO? Just for yourself? Or for the about half-a-handful of poeple try to fix up this framework from it's base than just think about their own server? IDK for how long ArmA3 and AltisLife will be around - and as BlackFish noted: ArmA3 seems to be already planed for EOL (although I wonder as the big 1.2 update was just announced) and there's an ArmA4 already in the planing - with all new scripting. Unless you have a big dev-community who wants to stick to it: Who's gonna read it?

It's completely not developer-friendly. Moreover, Arma 3 is not developer-friendly [...]

I don'T know about ArmA3 itself - but as for ArmaLife it was never meant to be dev friendly. As said: The original ArmaLife back then for Arma2 was done by only a single person (or if it already was a team back then I guess it was very small) - noone ever had in mind Altis Life would become that popular that it would become the reason for someone (like me) to buy the game just to play this one type of custom mission. And as ArmA2 and ArmA3 share a lot of base code lot was just copy'n'paste from the original ArmA2Life mission instead of a clean re-write from scratch. Would it had been better? For sure it would had been - but there was no need for.

I have looked at the wiki, and for me it's just a joke. [...]

As I said: Then ask for permission and feel free to do what ever you may see fit - but please: DO NOT bloat up the source files. Why a normal player has to download several 100 kB of doc? It all ends up in the mission file - unless you have some automated process to clean it up before "realese". If you have a look at the "maverick" tools from "TheProgrammer" supposed to obfuscated your mission - it adds a whopping 250kB random crap in the leading header just to F* up common PBO tools - and anyone who wants to play such a mission has to download all of those 250kB just so the server owner can have a nice sleep at night without fearing that his custom changes gets stolen. TLDR: Who wants to reverse a PBO and has some time to spare WILL crack it - there even tools to help you.

I know that comments in the file are not the best option, but it can help sometimes.

NO! Bloating up source with doc and comments explain what some line of code does only shows that your code is so bad that it isn't self-explaining anymore. In such case you should re-write the code instead of adding comments to explain it.

... code ...

Sorry, but no need to spam-copy code - just refernce the file by name we all can look it up ourself. Thanks.

And also some lines break are missing to improve readability.

Ok, fair point - but again: IT NEVER WAS MEANT TO!

Maybe you don't care about it, but for beginners or for some people who work on the mission, it's very important. I know some people who want to code, and I tell them to not use any function of the AltisLife Mission, even if some functions are cool because it's completely time-consuming.
Maybe I'm too accustomed to web development and software development, but even if the smallest NPM package has documentation and for the functions, a complete description in comments in the file.

If I make this issue, it's because you are a team, and it can be considered a general improvement for the mission.

I'm not part of the team but also just some random player who climbed up the latter two steps - and also be a hobby java programmer for the past 15 years. And sure I also cringe about the lack of documentation - but did you had a look at the BI wiki? It's not better. Just to give YOU an example: Have a look at EventHandlers - you'll find something like: "parameters: X - object, Y - object, Z - object" - ok, then you click on Object to get some information about this datastructure, to see what members it has and what functions you can perform on them - and then you get: "yea, object has some sub-types: A, B and C" - that's it.
ArmA3 itself and the official resources are very unfriendly for beginners - one really need some years of solid experience in some high-level languages like Java or C# (just to name two popular ones) to have a starting point. If you new to programming at all - yea, you may can call yourself a "scripter" - but if you really want to mod Arma3 and work with this rather complex framework without it please don't blame the framework for mistakes made back when ArmA2 was in dev at BI.
Also: There isn't a issue template for nothin. Issues on Github are meant to inform the dev about issues in the project - not to post suggestions like on a bulletin board. If you want to help the way on Github to go is to fork and file a pull request with your changes.

TLDR: You call yourself a "web-dev" - hm, k, HTML is, by its name, not a programming but rather a markup langauge - just sayin. Without any personal offense - but I think you missed to point why this framework is so bad and why it's heavily being worked on (look at the commit changes for master branch).

It's not like your "issue" hasn'T some valid points - but the issue section isn't the right place to discuss this.

[klmunday]

TL;DR: Clear and concise documentation on files that need it is always beneficial, it doesn't matter if not everyone uses it. This is not a place for insults.

I agree that documenting some of the functions used within Altis Life would be useful. Although by the looks of it most of your arguments for adding documentation seem to be with structure and flow, things like tag_fnc_functionname actually being the file fn_functionname. However, these are restrictions from arma and unless functions are defined as a global variable is as far as I'm aware unavoidable.

Perhaps some light documentation is needed, this would preferably be left outside of the mission files themselves for reasons highlighted by others (mission file size bloat etc). However PBO packers exist that can remove comments from the packed files. Regardless, I'm sure a documentation folder would be fine if documentation was done as separate files.

I think to address some of the comment issues (such as the function names) could instead be detailed in a "developer's guide" for Altis Life. This could detail common shortfalls people experience. This could even be handled in the repo's wiki, although i'm not sure if it's possible to give non-contributors access to edit it.

@cryptearth
I'm quite confused by some of your statements

Who's gonna read it?

Anyone who reads any documentation when working with code? As a "hobby java programmer for the past 15 years" I'm sure you've read plenty. There's no reason not to.

Ok, fair point - but again: IT NEVER WAS MEANT TO! - (readability)

Any developer should want their code to have a good level of readability. It especially helps with large projects when revisiting older files. Again, as a developer with 15 years experience you should understand this.

If you have a look at the "maverick" tools from "TheProgrammer"

The tool in question is not a product on that site. I'm also not sure on what relevance it has to this issue.

TLDR:

web development is not just confined to markup and stylesheets. You had some valid concerns but your approach to conveying them was condescending and frankly rude. This behaviour is not welcome here.

This issue highlights that there is a lack of high quality documentation for a lot of functions which people often come to the Discord server to specifically ask about. If someone wants to write some documentation they are more than free to. However, I'm going to close this issue since it has become a drama thread.

If anyone wants to create some documentation please do.

[ghost]

@klmunday
May let me address your questions about my comment:

• about "Who's gonna read it?"
  The way I read the issue is that @SteezCram seem to want to put "doc comments" in the source files. Ok, in languages that gets compiled and hence these are striped out of the resulting code this may be fine. But in an ArmA3 PBO all the files are just packed (in a rather unsual format I have to say - but I guess BI had some reason not just using something common like (g)zip with already existing libs) - and hence bloating up these files, which in the end are what's to be downloaded by the players (again: bad netcode - so every kB less should be prefered), should be avoided for this very reason. No "regular player" will ever read them - so have them to download several kB (or even in the order of MB) of data they never see and don't need using the existing netcode to download missionfiles in-game isn't just a bad idea but in fact effect players on the server. It sure makes a difference to just download 4MB clean of anything not needed or 10MB with 6MB worth of nothin.
  As for developers: I can't speak for anyone of you, but at least I expect something like I'm used to from the JavaDoc (or MSDN as for the C# example) - not source files full of comments. They way the mentioned Config_Master.hpp is filled with all those comments instead of make up a clean table here on Github on the Wiki sure makes me cringe - but looking in the history it's been that way since at least 2016 - maybe even for way longer and noone even bothered to clean this up for the past few YEARS!

• about readability
  Yes, you're correct that I prefer readable code - in fact, as a Java programmer I'm very used to the Java Coding Conventions - which are in place that every Java dev at least somewhat writes the same style of code making it easier for others to read it - and still even senior java devs write lines from time to time I think: When do you want to actually start to write "readable" code? My point is about @SteezCram is like "omg, why?" and I just replied with: "cause the one-man show never meant it to". It's a bit like to ask why a baby poops in its diapers: It's not meant to expected that a new born knows how to proper use a toilet. Same goes for this code: The time it was written it wasn't expected by its author to be read by someone else - let alone it become what it's today - so the lines were written with the knowledge the author had back then - wich resulted in what's common kown as spaghetti code. So, if @SteezCram thinks this is an issue - k, feel free to be my guest - but at least let me point out that on Github the way to make additions is by forking the project and file a pull request with your changes - not bloating the issues with it. And yes, I do know that a lot of strangers in fact do have some problems with me and that I just write down what I think - but I don't hide behind the bushes of politeness - if I think someone failed I to write it that way. If the answer is "delete and block" cause someone doesn't have the balls to stand it - k, I guess no point for me to further bother with it. At least give me the chance to reply before you silence me.

• about those tools
  I don'T know sh!t about those "maverick" obfuscator or this TheProgrammer site and what not - all I know is they all make money out of what BI basically had forbidden in a rather clear statement. So, if someone builds some randomizer and asks for money although the owner of the IP clearly stated one may NOT do so - and gets payed instead of slaped for it - nice luck bud, you got away with it. The point is: There're a lot of even big teams invested years into ArmA3 itself and in the ArmaLife project - and they make money out of it - so it seems it can't be that hard to figure it all out. And as noone bothered for years why now someone just creeps up like: "hey, you forgot some comments in your mess of code" - pff - KTHXBAI

• TLDR
  I know what web deving is - and as also pointed out by @blackfisch: This is F*ing ARMA - not you all nice documented new age fancy HTML5-era web-crap ... don't cry about it's rather rough around its edges - take it as given or go your own ways. I'm not the one tried to compare aples with peachs - @SteezCram tried to - I just pointed out that even try to was pointless in the first place.

[ghost]

If you want another example: Look at PR #668
Ok, neat idea to auto-refactor the "==" - but also nice F* up as for pushing a commit without testing before ... as a normal user it's like: "yea, devs, something's wrong" ... as a dev: "dude, it would had been nice to test it before you push the commit to the repo" - which again also makes me cringe.
It's not insulting or attacking someone presonal - I don'T know anyone of you - but this doesn't stop me from shouting a loud: "hey, you F#ed up dude" ... sure, I may harsh some times - and yes, I do know that some people feel insulted and think I'm just the way as I hide away behind the anonymity of the internet - but life told me: If you tell someone face to face they F#ed up it ends in either of two ways: they run away crying - or start attacking me physical - I never got a reply like "k, you may help me fix?" even once ... I just started to don't worry about it anymore - I just got dull in that way ... for me it's not "eat it OR die" but rather "swallow AND die" ...

[klmunday]

@cryptearth This conversation is going in circles, I'll end on a few remarks

But in an ArmA3 PBO all the files are just packed

True, however not all pbo packers are equal. There are some that when packing, parse each file and remove comments etc. Something like this would resolve the problem if a server owner found it that much of a problem. Which being honest, most bloat their missions with image files anyway, most missions you see on popular servers are usually 50-70MB. I agree that minimising this as much as possible is good. However it can be done in packaging tools, you could even do it in your own!

The time it was written it wasn't expected by its author to be read by someone else

I am confident that nearly all if not every file has been edited significantly since the project was published. It has been around 6 years. The language has developed significantly since then and so has the mod.

I don't hide behind the bushes of politeness

There's making a point and there's being an arse though. Whilst your points were valid you tainted them by being an arse. Issues like this are intended to be an open discussion and whilst I believe there shouldn't be any politics involved, people should still be courteous. People are capable of disagreeing productively.

At least give me the chance to reply before you silence me.

I have no intention of "silencing" you. I am merely asking you to conduct yourself in a productive manner.

There're a lot of even big teams invested years into ArmA3 itself and in the ArmaLife project - and they make money out of it

See the CC - NC license. I do agree that servers shouldn't be able to monetize purely the base content etc. However, that is not a discussion related to this issue.

It's not insulting or attacking someone presonal - I don'T know anyone of you

It's not about being insulting or personal attacks. It's about being respectful in an open discussion. No one's going to take your point seriously if you're being that way.

People are free to make issues to discuss future features and things that may be beneficial. People are also free to submit pull requests with their desired changes. We just expect people to be respectful of others.