Angband.oook.cz
Angband.oook.cz
AboutVariantsLadderForumCompetitionComicScreenshotsFunniesLinks

Go Back   Angband Forums > Angband > Development

Reply
 
Thread Tools Display Modes
Old July 19, 2010, 14:02   #11
nppangband
NPPAngband Maintainer
 
Join Date: Dec 2008
Location: Stat Gain, Angband
Posts: 926
nppangband is on a distinguished road
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.
nppangband is offline   Reply With Quote
Old July 19, 2010, 14:23   #12
konijn_
Hellband maintainer
 
konijn_'s Avatar
 
Join Date: Jul 2007
Location: New York, the Big Apple
Age: 42
Posts: 367
Donated: $120
konijn_ is on a distinguished road
Quote:
Originally Posted by nppangband View Post
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.
__________________
* Are you ready for something else ? Hellband 0.8.8 is out! *
konijn_ is offline   Reply With Quote
Old July 19, 2010, 14:57   #13
Nick
Vanilla maintainer
 
Nick's Avatar
 
Join Date: Apr 2007
Location: Canberra, Australia
Age: 54
Posts: 7,910
Donated: $60
Nick will become famous soon enough
Quote:
Originally Posted by konijn_ View Post
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.
__________________
One for the Dark Lord on his dark throne
In the Land of Mordor where the Shadows lie.
Nick is offline   Reply With Quote
Old July 19, 2010, 21:07   #14
Timo Pietilš
Prophet
 
Join Date: Apr 2007
Location: Climbing up from hole I just dug.
Posts: 4,096
Timo Pietilš is on a distinguished road
Quote:
Originally Posted by nppangband View Post
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.
Timo Pietilš is offline   Reply With Quote
Old July 19, 2010, 23:18   #15
Magnate
Angband Devteam member
 
Join Date: May 2007
Location: London, UK
Posts: 5,057
Magnate is on a distinguished road
Send a message via MSN to Magnate Send a message via Yahoo to Magnate
Quote:
Originally Posted by Pete Mack View Post
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.
Magnate is offline   Reply With Quote
Old July 20, 2010, 02:36   #16
nppangband
NPPAngband Maintainer
 
Join Date: Dec 2008
Location: Stat Gain, Angband
Posts: 926
nppangband is on a distinguished road
Quote:
Originally Posted by konijn_ View Post
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::
nppangband is offline   Reply With Quote
Old July 20, 2010, 04:11   #17
Nick
Vanilla maintainer
 
Nick's Avatar
 
Join Date: Apr 2007
Location: Canberra, Australia
Age: 54
Posts: 7,910
Donated: $60
Nick will become famous soon enough
Quote:
Originally Posted by nppangband View Post
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.
__________________
One for the Dark Lord on his dark throne
In the Land of Mordor where the Shadows lie.
Nick is offline   Reply With Quote
Old July 20, 2010, 11:38   #18
Pete Mack
Prophet
 
Join Date: Apr 2007
Location: Seattle, WA
Posts: 5,474
Donated: $40
Pete Mack is on a distinguished road
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 Mack is offline   Reply With Quote
Old July 20, 2010, 15:18   #19
konijn_
Hellband maintainer
 
konijn_'s Avatar
 
Join Date: Jul 2007
Location: New York, the Big Apple
Age: 42
Posts: 367
Donated: $120
konijn_ is on a distinguished road
Thumbs up

Quote:
Originally Posted by Pete Mack View Post
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.
__________________
* Are you ready for something else ? Hellband 0.8.8 is out! *
konijn_ is offline   Reply With Quote
Old July 20, 2010, 16:03   #20
Nick
Vanilla maintainer
 
Nick's Avatar
 
Join Date: Apr 2007
Location: Canberra, Australia
Age: 54
Posts: 7,910
Donated: $60
Nick will become famous soon enough
Quote:
Originally Posted by Pete Mack View Post
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...
__________________
One for the Dark Lord on his dark throne
In the Land of Mordor where the Shadows lie.
Nick is offline   Reply With Quote
Reply


Currently Active Users Viewing This Thread: 1 (0 members and 1 guests)
 
Thread Tools
Display Modes

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is On
HTML code is Off

Forum Jump

Similar Threads
Thread Thread Starter Forum Replies Last Post
Trying to understand the Angband 3.X source code nppangband Development 62 July 11, 2010 19:20
Angband Code Interface to GUI meeshoo Vanilla 50 February 3, 2009 18:18
strange C code in Angband (am I reading this right?) will_asher Idle chatter 3 February 4, 2008 10:07
Updating Vanilla for dummies Dragonboneman Vanilla 7 August 12, 2007 23:12
Looking through the code K.I.L.E.R Vanilla 5 July 11, 2007 09:01


All times are GMT +1. The time now is 15:06.


Powered by vBulletin® Version 3.8.11
Copyright ©2000 - 2020, vBulletin Solutions Inc.