Angband code for dummies?

[nppangband]

Yeah, we used to make fun of that one line of comment per line of code, but it really helps newbies apparently.

T.

Yep, one comment for each line is perhaps overkill, but there are whole files (such as ui-menu.c) that are barely documented now. There has to be some sort of happy medium.

And I apologize for this little soapbox speech I am about to make, but I knew nothing about coding when I considered making a variant. It was only the the highly detailed commenting in the Vanilla source that made me want to go ahead and try to make NPP. And I know plenty of other maintainers who made some great variants over the years that were in the same boat. They are also where many of the ideas that are now in Vanilla were developed and perfected. I am glad that Angband is under active development again, but I believe it is the rich variety that the variants offer that keeps people playing this game for decades. And it was Ben Harrison's code cleanup that made it all possible. ::end soapbox::

[Nick]

Yep, one comment for each line is perhaps overkill, but there are whole files (such as ui-menu.c) that are barely documented now. There has to be some sort of happy medium.

And I apologize for this little soapbox speech I am about to make, but I knew nothing about coding when I considered making a variant. It was only the the highly detailed commenting in the Vanilla source that made me want to go ahead and try to make NPP. And I know plenty of other maintainers who made some great variants over the years that were in the same boat. They are also where many of the ideas that are now in Vanilla were developed and perfected. I am glad that Angband is under active development again, but I believe it is the rich variety that the variants offer that keeps people playing this game for decades. And it was Ben Harrison's code cleanup that made it all possible. ::end soapbox::

No need to apologize. I think I am more in agreement with every word of this than anything else ever.

[Pete Mack]

OK, OK, mea culpa; mea maxima culpa!
I will write some comments for ui-menu.c (In my defense, I put lots of comments in the .h file.)

Oh yeah, and ui-menu.c isn't "thousands" of lines; only 922 including comments.

[konijn_]

OK, OK, mea culpa; mea maxima culpa!
I will write some comments for ui-menu.c (In my defense, I put lots of comments in the .h file.)

Oh yeah, and ui-menu.c isn't "thousands" of lines; only 922 including comments.

Thanks Pete.

T.

[Nick]

OK, OK, mea culpa; mea maxima culpa!
I will write some comments for ui-menu.c (In my defense, I put lots of comments in the .h file.)

Oh yeah, and ui-menu.c isn't "thousands" of lines; only 922 including comments.

Don't be too hard on yourself - I managed to work out how to use your menus, so it can't have been that bad. And there are other files where you pretty much have to make do with function names for comments (game-event.c, I'm looking at you).

In any case, development has been rapid lately, and it's not all that surprising that documentation hasn't kept up. It's a pity V doesn't have fully comprehensive doxygen support, like some variants...

[nppangband]

OK, OK, mea culpa; mea maxima culpa!
I will write some comments for ui-menu.c (In my defense, I put lots of comments in the .h file.)

Oh yeah, and ui-menu.c isn't "thousands" of lines; only 922 including comments.

Pete - It is some great code. I just used it as an example because I had just spent some time getting NPP features like store services to work alongside the store inventory inside the new interface. In terms of ui-menu.c, most of it worked automatically. Ui_menu added the services right alongside the store inventory and I could highlight them with a mouseclick without having to de-bug or fix anything. I half expected it to have to make major changes, and I didn't. I am a big fan of how it works, even if I don't quite understand it yet.

For example: two of the store services in NPP are increase stat and restore stat, kind of like buying the potions and quaffing them. Currently, the player can purchase the service by mouseclick, but when it comes to picking a stat to restore/increase, they have to use the keyboard, because it isn't apparent to me how to create and display a list of the stats that need to be restored or increased, and have the player pick from the display with the mouse. No big deal, it is on my to-do list and I am sure I will figure it out when I get to it. But unless I missed it there is nowhere that says "here are the steps to create a menu, display it on the screen, and erase it after the user selects from a list." I don't think the code needs painstaking line-by-line commenting, just a quick paragraph or two on how to create an interactive list from scratch.

Nick had a better example, with game-event.c. I haven't looked too closely at it yet, but it isn't apparent to me why that was added, what was wrong with the code it replaced, or how it makes the game work better.

[Nick]

Nick had a better example, with game-event.c. I haven't looked too closely at it yet, but it isn't apparent to me why that was added, what was wrong with the code it replaced, or how it makes the game work better.

My understanding is that it is an interface between the game and the UI, so the game says "this happened" and the UI works out how to draw it. But I certainly don't have the detail down.

[rogerhaines]

I've looked at the code, and it's nothing like spaghetti. There's no sauce.
LOL!!! But seriously, it's not. C++ is very object orientated, which makes spaghetti code hard to implement.
Python, on the other hand...... is different.