Angband code for dummies?

[nppangband]

In my humble opinion, the comments in ui-menu.c need to go in much greater detail about how it all works. Although the current Angband code is cleaner, more efficient, and on the whole impressively written, the nice thing about the Ben Harrison code was that virtually every function in the codebase was commented so well that soembody with almost no coding experience could look at it and understand how it worked without having to decipher thousands of line of code.

[konijn_]

Originally Posted by nppangband

In my humble opinion, the comments in ui-menu.c need to go in much greater detail about how it all works. Although the current Angband code is cleaner, more efficient, and on the whole impressively written, the nice thing about the Ben Harrison code was that virtually every function in the codebase was commented so well that soembody with almost no coding experience could look at it and understand how it worked without having to decipher thousands of line of code.

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

T.

[Nick]

Originally Posted by konijn_

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

Speaking as a newbie, hell yeah.

[Timo Pietilä]

Originally Posted by nppangband

In my humble opinion, the comments in ui-menu.c need to go in much greater detail about how it all works. Although the current Angband code is cleaner, more efficient, and on the whole impressively written, the nice thing about the Ben Harrison code was that virtually every function in the codebase was commented so well that soembody with almost no coding experience could look at it and understand how it worked without having to decipher thousands of line of code.

Exactly my point. I used to be able to tell what things do. Now I usually have no clue about them, and don't even know what to look for.

[Magnate]

Originally Posted by Pete Mack

Timo, I think you are wrong on this.
It used to be, the damage calculation was mixed up in the code, and if you changed how (say) darkness worked, you would have to change code in two or three places.
Now it's all in a single .h file.
It could be better (and is, in NPP and Un). But it's much better than it was.

Praise indeed - thanks Pete!

Timo - I don't think *any* project split into this many files has an intuitively obvious system for which functions belong where - that's precisely why IDEs have developed sophisticated methods for tracking and following code. So I don't think angband is more spaghetti-like than other projects of its size (and age - we wouldn't start from here, of course).

There is a fair point that the quality of comments in the code is variable. I think perhaps, without pointing any fingers, that the significant amount of development by a large number of people over the past few years has had the unfortunate side-effect of decreasing the overall value of comments - we all have different styles and different understandings of what's required, and it's hard to try and think like someone who doesn't know the code when your priority is committing the bugfix.

[nppangband]

Originally Posted by konijn_

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]

Originally Posted by nppangband

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_]

Originally Posted by 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.

Thanks Pete.

T.

[Nick]

Originally Posted by 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.

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...