Vanilla coding conventions

[Marble Dice]

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.

[Nick]

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.

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.

[Marble Dice]

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.

[Nick]

OK, here's a start - basically the old coding guidelines from trac with some minimal formatting update, and an aspirational introduction

[Marble Dice]

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?

[Julian]

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.

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

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.

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]

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.

[Marble Dice]

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.

[Pete Mack]

Curly brackets are properly called braces, except for some reason in programming.

[Nick]

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

[MITZE]

Perhaps a dumb question (if I understand properly what's being conveyed anyway), but why the "tabs of four spaces" convention?

[Marble Dice]

Perhaps a dumb question (if I understand properly what's being conveyed anyway), but why the "tabs of four spaces" convention?

That's just a recommendation to set your editor to display tabs as 4 spaces, as your tab display width also has a (usually minor) impact on where you break lines.

[Nick]

That's actually a really good start, and about what I would have expected from looking at the code.

I think it's probably originally written by takkaria, or maybe Antony Sidwell; it's what I've been working off since I started V development.

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.

My gut agrees with Julian on this one, but I don't know how much of that is just habit (there's a joke about going to great lengths here...). In many ways it would be easier to have a bit more line length to play with, and there is certainly the odd line which goes over 80 - mainly to not break quoted strings. Not sure, more discussion needed.

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?

I think it has been expressed as a project preference in the past, and I'm inclined to stick with it, mostly at least. I use // mainly to temporarily comment out code or for other things I'm tentative about, so doing a search for it enables me to find where something temporary has accidentally become permanent, or (as in some cases in obj-info.c) where there is something I'm not happy about that I want to do better. I'm inclined to write it into the document as a strong preference.

[Marble Dice]

In many ways it would be easier to have a bit more line length to play with, and there is certainly the odd line which goes over 80 - mainly to not break quoted strings. Not sure, more discussion needed.

I'll follow the convention of course but if it's okay to go past 80 "just a little bit" when you "feel like it" then that's not really much of a convention. Obviously line wrapping is important, but that's exactly why I want a little more room - to make the most readable blocks of code. I'll just pretend I didn't notice I had 85 characters on that line unless you call me out on it.

I think it has been expressed as a project preference in the past, and I'm inclined to stick with it, mostly at least. ... write it into the document as a strong preference.

I think a convention is good for consistency, and I certainly wouldn't use // with as one-sided as the source currently is. I count 102 instances of // and 18,941 instances of /*.