Common coding style - Githubissues

g4v4g4i commented 8 years ago

We should agree on a common coding style:

intendation: AnneMarie worked with 2 chars while Daniel with 4. I would prefer 2 since most of the code is with 2.
commenting style: a. procedures: I would say we put comments on top b. others: if lengthy on top, if short it can go on the side
brackets: a. if / then: I think we can use AM's style which is very common b. closing brackets: I think it would be great if the closing bracket would have the intendation that reflects the level of the hierarchy which it closes. I'd like to avoid e.g. two closing brackets in a row on the same level. AM told me that the netlogo editor has a bit of a strange behavior in that respect.
other issues: a. often people reflect differences between local and global variables in the naming of these which improves readability. Should we begin to think about that? b. Other points?

daimpi commented 8 years ago

I'm fine with 2 chars intendation ☺️
I agree with procedure description at the top. But for description what a certain line in the procedure is doing, I think it is best to have it directly in the line even if it gets a bit longer… good editors have automatic line break anyway so it shouldn't look messy.
With brackets I agree as well. Would be nice to make them with proper intendation unless we're talking maybe about a short bracket like e.g. [...] with [color = red]. I dunno about funny behavior of the Netlogo editor b/c I'm currently using notepad++ with a customized language setup for netlogo which makes everything look quite nicely structured.
Fine with me too ☺️

daimpi commented 8 years ago

Regarding 4b. I think if we define or set variables it would be helpful to know which format they're in (list, string, agentset,…) and how their content looks like e.g. for a list a comment could look like: list: [[ (argument a) color a] [ (argument b) color b] …] This simplifies in my experience checking and understanding the code especially when references to list items is made somewhere in the code by something like last but-last.

g4v4g4i commented 8 years ago

I agree with 4b.

Concerning max width: although good editors will line-break it for you, the intendation will get destroyed and code will look messy. I'd still opt for a roughly 80 chars width (as seems pretty standard among coders anyway). This has also other advantages (e.g., printing, putting two instances of code beside each other on a standard sized screen, etc.).

daimpi commented 8 years ago

Regarding the discussion of 2b: actually for me it doesn't destroy intendation. Here is an example of hefty in-procedure-commenting:

notepad netlogo code

I dunno… for me when it comes to a trade-off between style and clearness/understandability of the code I'd rather go for the latter. Additionally comments can probably also be completely hidden/represented visually differently by an editor which recognizes the syntax. Maybe we could try to explore such options before hard limiting the length of in-procedure-comments too much? But though I personally feel that 80 chars is to little sometimes, I'd generally agree that we probably don't want whole novels as comments in the code: my hefty comment example from above has it's longest comments still at around 250 chars. Descriptions which get really long should anyway go to the "Info" section of the model and imho that's also true for above-procedure-comments. What do you think? ☺️

g4v4g4i commented 8 years ago

Same in emacs. Nevertheless, e.g. if you look at code in github you have quite a mess with lengthy lines. Anyway, when I learned to code we had still squary screens with comparatively low resolutions and people were more concerned about this than nowadays. So if you and AnneMarie are for no restrictions on column width, I will not object ;-)