Page 1 of 1

Zscript mods to examine for learning purposes?

Posted: Sun May 26, 2019 1:50 pm
by affandede
Which zscript mods are suitable for learning zscript and modding overall? I. e. commented extensively and relatively easy to understand what's going on, what does what etc.

Re: Zscript mods to examine for learning purposes?

Posted: Mon May 27, 2019 9:10 am
by MFG38
affandede wrote:commented extensively
You'd be hard-pressed to find anything extensively commented, ACS and DECORATE included. Most programmers don't seem to like doing that, even if it meant being able to help someone understand what does what in a piece of code.

Re: Zscript mods to examine for learning purposes?

Posted: Mon May 27, 2019 10:50 am
by m8f
NC HUD is well-commented.
Doom Tourism

And, in general, don't be afraid to read the code even if it isn't commented. Having the source available is already a blessing.

Re: Zscript mods to examine for learning purposes?

Posted: Mon May 27, 2019 12:03 pm
by Matt
The best commented ZScript I've seen is in the GZDoom source itself.

Re: Zscript mods to examine for learning purposes?

Posted: Mon May 27, 2019 3:00 pm
by affandede
Thanks for the replies, I will be looking into NCHud, Tourism Deluxe and gzdoom.pk3. By the way, I recently discovered that Guncaster and it's derivative Vindicated is also fairly well documented. Would you suggest examining your Hideous Destructor for learning, Matt?

Re: Zscript mods to examine for learning purposes?

Posted: Mon May 27, 2019 5:23 pm
by Matt
For getting used to ZScript, absolutely not - the posts I made in Tutorials were designed to get some of the basic stuff down that would get lost in the details if someone looked at HD.

For learning how to do stuff in ZScript that would normally be prohibitively difficult to hack in Decorate or SBARINFO, or how to do more streamlined ZScript functions for things that used to require lots of inventory hacks and state jumps, absolutely.

Re: Zscript mods to examine for learning purposes?

Posted: Tue May 28, 2019 12:52 am
by Player701
Commenting code can be useful to improve maintainability, so that when you return to your project after taking a break, you know why this part of code is in here and why it is important. Granted, some people may not agree with me, because in general, code should explain itself, so that you do not need comments in the first place. But it is not always possible, especially with ZScript.

For example, RRWM (shameless self-plug :P ) is extensively commented, especially the UI code which is quite complicated (though it may not be evident from what you see in the game as a result). Most of the comments are part of the code style - each and every method and field has a comment block with a short description. And indeed, most of what's featured there would be quite difficult or even outright impossible to implement with DECORATE and co. - the same goes for many other ZScript-based mods.

Re: Zscript mods to examine for learning purposes?

Posted: Tue May 28, 2019 6:50 am
by Graf Zahl
Player701 wrote:Commenting code can be useful to improve maintainability, so that when you return to your project after taking a break, you know why this part of code is in here and why it is important. Granted, some people may not agree with me, because in general, code should explain itself, so that you do not need comments in the first place. But it is not always possible, especially with ZScript.

It's not ZScript, but when I started my current job roughly 2 years ago I inherited a source base of several 8000+ source files, all of it barely commented. It took over a year to get that into a state where I could work with it. Commenting one's source is generally important, even if it's merely a single one-line description what a function does.

Re: Zscript mods to examine for learning purposes?

Posted: Tue May 28, 2019 7:30 am
by Rachael
Graf Zahl wrote: It's not ZScript, but when I started my current job roughly 2 years ago I inherited a source base of several 8000+ source files, all of it barely commented. It took over a year to get that into a state where I could work with it. Commenting one's source is generally important, even if it's merely a single one-line description what a function does.
It's really not just that - it's a whole lot more important than you say even here.

Commenting helps the actual coder in the long run, too. If you stick with that for more than 10 years, guaranteed that you're going to forget what the code does, without comments. I've looked back on my old ZDoom submissions and was very thankful that I put the comments that I did, because it was confusing as hell without them.

If the code seems self-documenting, though (i.e. it's really really obvious what it's doing) I tend to comment far less.

Personally I am really bad with comments, but if I have to do a weird trick in the code I do have a habit of putting a comment so that I know why the code was made to do what it does later on.

Re: Zscript mods to examine for learning purposes?

Posted: Tue May 28, 2019 8:03 am
by Graf Zahl
Well written code should at least partially docxument itself, i.e. having function names that say something about what a function does, it is very important to split up larger tasks into smaller fragments to get some order (the abovementioned code base has multiple functions spanning 2000-3000 lines - good luck understanding those monstrosities.)

While I can understand why this probably happened (the guy writing that code was under constant pressure and had little time to do any maintenance), it was ultimately self-defeating. Even under pressure it is important to keep order, because otherwise all that bad code will come bite you in the ass later and make things even worse.

I was never able to talk to him because he left before I started the job.

Re: Zscript mods to examine for learning purposes?

Posted: Tue May 28, 2019 8:44 am
by Kinsie
It can also help to add personal notes and reminders to the code, in case something happens and you need to remember what you were doing. Basically the first thing I do when I start coding a new actor is write a two-or-three-line or so comment detailing the basic behaviour I want it to perform, so I have a goal to focus on and a reminder in case the overhead kitchen cupboard dumps a bunch of plates on my head and I develop crippling amnesia.

Image

Re: Zscript mods to examine for learning purposes?

Posted: Tue May 28, 2019 11:42 am
by JPL
Thanks for the mention of my Tourism mod. The (1000s of lines!) Zscript for my mod Mr Friendly is also pretty extensively commented, which as an ongoing project helps a lot when I return to it after a few months away: https://jp.itch.io/mr-friendly