Angband.oook.cz
Angband.oook.cz
AboutVariantsLadderForumCompetitionComicScreenshotsFunniesLinks

Go Back   Angband Forums > Angband > Development

Reply
 
Thread Tools Display Modes
Old July 16, 2021, 00:11   #1
Marble Dice
Swordsman
 
Join Date: Jun 2008
Location: Portland, OR, USA
Posts: 412
Marble Dice is on a distinguished road
Vanilla coding conventions

I've seen reference to coding conventions here or there, but the links I've encountered are broken. Is there a current conventions document anywhere? I have a reasonable idea of what to expect from looking around the code, but it's good to have them written down somewhere convenient, too.

On a related note, is there a development chat somewhere other than this forum? I know there is an #angband-dev on freenode.net IRC, but I'm not sure if that's the current or previous IRC.
Marble Dice is offline   Reply With Quote
Old July 16, 2021, 01:39   #2
Nick
Vanilla maintainer
 
Nick's Avatar
 
Join Date: Apr 2007
Location: Canberra, Australia
Age: 56
Posts: 9,170
Donated: $60
Nick will become famous soon enoughNick will become famous soon enough
Quote:
Originally Posted by Marble Dice View Post
I've seen reference to coding conventions here or there, but the links I've encountered are broken. Is there a current conventions document anywhere? I have a reasonable idea of what to expect from looking around the code, but it's good to have them written down somewhere convenient, too.
That's a really good point. There was some stuff (by takkaria, IIRC) on trac.rephial.org, which has been taken down; I should chase it up and get it hosted somewhere. There is a bunch of explanation of how bits of the code works in both docs and src/doc directories, but nothing on actual coding conventions.

Quote:
Originally Posted by Marble Dice View Post
On a related note, is there a development chat somewhere other than this forum? I know there is an #angband-dev on freenode.net IRC, but I'm not sure if that's the current or previous IRC.
Still #angband-dev, but now moved to irc.libera.chat. It's pretty quiet, but talking may well fix that There is also a bit of dev discussion that goes on here, and also quite a bit on individual Github issues and pull requests.
__________________
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 16, 2021, 02:31   #3
Marble Dice
Swordsman
 
Join Date: Jun 2008
Location: Portland, OR, USA
Posts: 412
Marble Dice is on a distinguished road
Quote:
Originally Posted by Nick View Post
I should chase it up and get it hosted somewhere.
If you can find it, that'd be awesome. I think the best place for conventions is alongside the source in the repository itself, and I believe github has support for this as well via CONTRIBUTING.md files: https://docs.github.com/en/communiti...y-contributors

They can document pull request guidelines, style conventions, whatever you want.

If you find the old conventions from trac (and they're still applicable), maybe just slap it into a CONTRIBUTING.md and we can go from there. I'll probably be bugging people with more conversations about it in the near future.
Marble Dice is offline   Reply With Quote
Old July 17, 2021, 00:39   #4
Nick
Vanilla maintainer
 
Nick's Avatar
 
Join Date: Apr 2007
Location: Canberra, Australia
Age: 56
Posts: 9,170
Donated: $60
Nick will become famous soon enoughNick will become famous soon enough
OK, here's a start - basically the old coding guidelines from trac with some minimal formatting update, and an aspirational introduction
__________________
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 17, 2021, 01:09   #5
Marble Dice
Swordsman
 
Join Date: Jun 2008
Location: Portland, OR, USA
Posts: 412
Marble Dice is on a distinguished road
That's actually a really good start, and about what I would have expected from looking at the code.

I agree with almost all of the recommendations, but the one thing I'd really like to see changed is the 80 character line limit. Even my ancient 17" monitor can easily display up to 150 characters with multiple panes open. I'm not saying we have to go through and reformat everything but increasing the line-wrap recommendation to 120 or even 100 would make a world of difference. With a few indents in the mix, it can get hard to wrap lines in an clear and aesthetically pleasing location at 80 characters.

One other thing I've noticed is there seems to be a preference for inline /* block-style */ comments instead of // single line comments. The block-style comments make sense for function headers, but I find the // comments much easier to work with for inline comments. Is this actually a project preference or just what's happened?
Marble Dice is offline   Reply With Quote
Old July 17, 2021, 04:26   #6
Julian
Apprentice
 
Join Date: Apr 2021
Posts: 89
Julian is on a distinguished road
Quote:
Originally Posted by Marble Dice View Post
That's actually a really good start, and about what I would have expected from looking at the code.

I agree with almost all of the recommendations, but the one thing I'd really like to see changed is the 80 character line limit. Even my ancient 17" monitor can easily display up to 150 characters with multiple panes open. I'm not saying we have to go through and reformat everything but increasing the line-wrap recommendation to 120 or even 100 would make a world of difference. With a few indents in the mix, it can get hard to wrap lines in an clear and aesthetically pleasing location at 80 characters.
Long lines are harder to read, even on a big screen.

Code:
static void get_known_elements(const struct object *obj,
				const oinfo_detail_t mode,
				struct element_info el_info[])
Is easier to read (If the indents are right) than
Code:
static void get_known_elements(const struct object *obj, const oinfo_detail_t mode, struct element_info el_info[])
Also, not all screens are big. Many, many people only have laptops, and once the sidebars of Xcode are taken into account, I don’t have _that_ much more than 80 characters.


Quote:
One other thing I've noticed is there seems to be a preference for inline /* block-style */ comments instead of // single line comments. The block-style comments make sense for function headers, but I find the // comments much easier to work with for inline comments. Is this actually a project preference or just what's happened?
This one may be because // comments are a newfangled innovation
Julian is offline   Reply With Quote
Old July 17, 2021, 04:38   #7
Julian
Apprentice
 
Join Date: Apr 2021
Posts: 89
Julian is on a distinguished road
Quote:
Originally Posted by Nick View Post
OK, here's a start - basically the old coding guidelines from trac with some minimal formatting update, and an aspirational introduction
AFAIK, normal usage is that brackets refers to [], and parens is used for (), but the coding style document disagrees.
Julian is offline   Reply With Quote
Old July 17, 2021, 08:37   #8
Marble Dice
Swordsman
 
Join Date: Jun 2008
Location: Portland, OR, USA
Posts: 412
Marble Dice is on a distinguished road
Quote:
Originally Posted by Julian View Post
AFAIK, normal usage is that brackets refers to [], and parens is used for (), but the coding style document disagrees.
I think this is regional actually. Here in the US, I feel like parenthesis and only parenthesis is used for (), while the term brackets is more common the UK. Wikipedia identifies round brackets (), square brackets [], curly brackets {} and angle brackets <> which sounds ridiculous to me but there you go.
Marble Dice is offline   Reply With Quote
Old July 17, 2021, 14:18   #9
Pete Mack
Prophet
 
Join Date: Apr 2007
Location: Seattle, WA
Posts: 6,594
Donated: $40
Pete Mack is on a distinguished road
Curly brackets are properly called braces, except for some reason in programming.
Pete Mack is offline   Reply With Quote
Old July 17, 2021, 14:21   #10
Nick
Vanilla maintainer
 
Nick's Avatar
 
Join Date: Apr 2007
Location: Canberra, Australia
Age: 56
Posts: 9,170
Donated: $60
Nick will become famous soon enoughNick will become famous soon enough
Quote:
Originally Posted by Marble Dice View Post
I think this is regional actually. Here in the US, I feel like parenthesis and only parenthesis is used for (), while the term brackets is more common the UK. Wikipedia identifies round brackets (), square brackets [], curly brackets {} and angle brackets <> which sounds ridiculous to me but there you go.
Correct - I am aware of the "correctness" of [] being brackets and () being parentheses, but also the use of bracket as a general term for any pair of concave inward delimiters. So along the lines of leaving the UK/US variation according to the first author, I'll leave it as is
__________________
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
Angband Coding Style calris Development 37 April 30, 2016 08:08
some more questions about coding Malak Darkhunter Vanilla 16 January 3, 2012 05:52
more variant coding woes will_asher Variants 1 February 10, 2011 06:18
Angband coding question will_asher Variants 10 September 3, 2008 23:03
Coding standard? Indentation? Bandobras Vanilla 10 May 24, 2008 20:46


All times are GMT +1. The time now is 16:39.


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