Comment on CodeFormatAndCommenting in amx-netlinx-common

[amx-netli...@googlecode.com]

Comment by jordevorstenbosch:

Why shouldn't you use the semi-colon to terminate lines? This is pretty
common practice to do, even if the compiler does it automatically. Is there
a specific reason you think it shouldn't be done?

A semicolon doesn't just make it easier for the compiler, it makes it
easier to read as well. Because you know where the line is (should be)
terminating.

That's why I disagree with this, but perhaps there's a good reason not too.
I'm curious about other people's views.

For more information:
http://code.google.com/p/amx-netlinx-common/wiki/CodeFormatAndCommenting

[amx-netli...@googlecode.com]

Comment by jska...@spireintegrated.com:

I second the use of semi-colons to terminate lines. Most of the time, the
compiler and I agree on the end of a line/command... but the couple of
times we have differed, the compiler did not inform me and I spent hours
trying to figure out what happened. The compiler does support them, it just
does not require them.

[amx-netli...@googlecode.com]

Comment by trueamx:

Other than use in rare single-line constructs, semicolon terminators
are completely superfluous in NetLinx. Semicolon statement terminators
at the end of lines add nothing to the code. Code will compile fine
with or without them. I know lines terminate when the statement has
ended (peren-newline, bracket-newline, doublequote-newline). The rules
don't change there. Adding them to the ends of lines in NetLinx is
equal only to decoration.

By allowing them, they are sure to be forgotten in some instances. The
code will still work, but this will hinder readability and hinders
using the code as a learning tool ("Why isn't this line terminated?
Why does it still work?")

I come from a programming background in C and PHP, so I'm very used to
semicolons as terminators. I also deal with languages that either
don't use them (PIC assembly) or that can use them, but usually
shouldn't (such as Haskell). I've gotten used to not using them in
NetLinx, even though it is similar to other popular languages, as they
are not necessary and they add nothing to the code.

[amx-netli...@googlecode.com]

Comment by kim.john.burgess:

To summarize the discussion across here, the forums and the dicussion list
so far we seen to have:

Commenting
Javadoc-ish seems to be the way to go. I'll work on documentation for
documentation :) based on this.

Tab width
Two competing options: 4 characters or 8. Currently 1 vote for 8 character
spacing and 3 votes for 4 (including me).

Column width
Again, two options currently in discussion: 80 character or 120 characters.
An 80 character width setup does have a lot of research to back its
validity and presents the main advantage of helping to enforce simplified
logic and reduce nesting.

Line termination
Currently this is going either way. Personally I'm with 'true' on this one,
the language doesn't utilize them and if code is structured _properly_
there should be no need for their use. Implimenting them is akin to
requiring 3 pairs of parenthesis around every set of function
parameters "just to be sure" (ie. `tmp = foo_bar(((x)))`.

Vertical alignment
This is something we need to discuss more.


Let the discussion continue...

For more information:
http://code.google.com/p/amx-netlinx-common/wiki/CodeFormatAndCommenting

--
Subscription settings: http://groups.google.com/group/netlinx-common-libraries/subscribe?hl=en

[amx-netli...@googlecode.com]

Comment by trueamx:

Columns - The big thing with 80 characters is that it was used because
consoles tended to have that many characters in width. Because we had text
consoles for so long, and then low resolution graphical screens, and we
didn't know what other people would have, 80 characters was a nice safe
point to be at. By sticking with 80, longer conditions will start to stack
vertically, and if the code isn't simple, it will be harder to tell at a
glance where one part ends and the next begins.

Hopefully none of us are using 80 column terminals anymore. :) I can live
with 80, and 80 is probably fine in a project like this, but I do prefer
more.

Vertical alignment - are you referring to variable names and initial
assignments and such? I prefer having them but I tend to both use and not
use them in my code. This is also somewhat uncommon in other languages. I
could go either way. Other than for large groupings of data though (like at
the beginning of unixtime.axi), for things such as stack_var declarations,
it's probably unnecessary.

For more information:
http://code.google.com/p/amx-netlinx-common/wiki/CodeFormatAndCommenting

[amx-netli...@googlecode.com]

Comment by kim.john.burgess:

I tend to use an 80 width column primarily beacuse I have my screens
rotated to portrait (http://bit.ly/2kRyJX). Aside from that their has also
been a bit a generally readability study done on column width (regardless
of available screen realestate) which has shown 80 characters to be a sweet
spot.

Vertical alignment - yes that's was I was referring to. What are people
thoughts on aligning any constact declarations and config settings at the
top of libraries, but keep everywhere else in line with the 'real world'.

[amx-netli...@googlecode.com]

Comment by jordevorstenbosch:

Kim your bit.ly link leads to something else.

Seeing as we're using 16:10 displays these days and generally landscape
screens I think 120 characters would be nice for colums. imo we should
stick to the styleguide we wanted and only change what is necessary. If you
guys really think it's that important to go to 4 i'm ok with it.

Kim I take it you don't use a laptop? (Because you have your displays in
portrait)

I use my laptop for development and got an extra 24" screen next to it.

@trueamx, I disagree on LT with you, because it does have an added value,
it makes it really clear to the other people programming what you intended
to do. Right now when I look back at old programs some (ex-)colleagues did
it's rather hard to see if they intended it to be terminated or not. A
simple semi-colon makes this clear. This also makes this source easier to
do for people who come from different programming languages, as semicolon
line termination is pretty standard. (exceptions here and there of course,
like you pointed out)

The code will still work, but this will hinder readability and hinders
using the code as a learning tool ("Why isn't this line terminated? Why
does it still work?")

Seeing as the debugger isn't good at all this is exactly the reason we
should do it imo. Because no line termination hinders the readability for
me.

It does the exact opposite for me, "I see he WANTED to terminate it here,
so that's how it works" instead of, mmm what was he doing here, shouldn't
this line be terminated?

And as a bonus, I was told the following at the amx programmer's
course "You don't *have* to terminate your lines, however it's *better
practise* to do so". When I asked, do you need to terminate your lines?

[amx-netli...@googlecode.com]

Comment by kim.john.burgess:

@jordevorstenbosch
Try this one: http://bit.ly/geekstation. I do use a laptop, but have it
docked the majority of the time. When I'm on site I tend to have
diagnostics side by side with the code.

Does the AMX compiler interpret semi colons as a line ending? I've never
actually tested this.

[amx-netli...@googlecode.com]

Comment by jordevorstenbosch:

@kim, son of a ****, jealousy strikes! :(

How did you hook up 4 screens to a laptop though? I only have 1 out
(mini-displayport). And I want.

From the help file of NS3:

_Note that semicolons are used in the example to terminate each line in a
breakpoint. The only time that the semicolon is absolutely necessary is
when a breakpoint is set at the last line of code. To keep things simple,
consider terminating each breakpoint with a semicolon._

[amx-netli...@googlecode.com]

Comment by trueamx:

So semicolons are only needed when debugging (breaking on specifically) the
last line of code.

[amx-netli...@googlecode.com]

Comment by jordevorstenbosch:

true, read the post I made above.

[amx-netli...@googlecode.com]

Comment by jska...@spireintegrated.com:

As far as I can tell, the compiler does interpret ; as a line terminator.
It doesn't matter to me one way or the other as my early code does not use
the ; and my current code does, so I am good either way.

I do like them for the fact that they do indicate when a line is expected
to be terminated by the coder, but I suppose for most instances, if this is
a problem, the code might be too obfuscated and should be rewritten to
avoid confusion?

[amx-netli...@googlecode.com]

Comment by trueamx:

Re: jordevorstenbosch, if it isn't clear when the line should be
terminated, the code likely isn't formatted very well. Look at String.axi -
is it unclear anywhere where a statement is terminated? What about
unixtime.axi (where this is more likely to be so)?

Re: training, it was the opposite for me - the other programmers were told
it is unnecessary and training continued without them. It's merely a style
candy preference.

Re: jsk...@spireintegrated.com, probably.

Another thing to add - what do we do about spacing multi-line statements
and conditions? For statements and argument lists, I usually tab twice on
the newline. For conditions, I tend to tab once then add an extra blank
line after the opening brace to visually seperate the condition from the
first statement.

[amx-netli...@googlecode.com]

Comment by jordevorstenbosch:

@true, I don't know if you program in any other languages, but I do and I
can't think of many languages that don't use the ; LT method. It's
generally considered bad practice not to implement it, but yes if it
_really_ isn't clear then it's most likely due to bad programming. But if
you add them then it's always clear *at a glance* and that's what is
important to me.

Considering that I think it's the _preferred_ way to go.

@jeff
Considering you guys wanna use 4 chars as the tab-width I think twice might
be nice on the newline.

[amx-netli...@googlecode.com]

Comment by jordevorstenbosch:

@true, also I think Jeff would appreciate it if you could remove the mailto
link in your message.

[amx-netli...@googlecode.com]

Comment by trueamx:

jordevorstenbosch, I didn't add markup for that in my post. Groups is
adding that automatically.

[amx-netli...@googlecode.com]

Comment by trueamx:

jordevorstenbosch, I didn't add markup for that in my post. Groups is
adding that automatically.

Regarding other languages, yes, I write a few. Of those that can use
semicolons and don't that I use, I can think of two offhand - Lua and
Haskell. (Bash scripting is certainly hackish, also has optional semicolon
usage and would make a third to this list; I guess it depends on if you
want to call shell scripting a language or not). Lua is not much different
than other procedural languages and can also use semicolons, but you won't
find much code that does. Why? They do nothing. And this is considering
that in Lua, it may not be visible at a glance where a statement ends
(though you'll rarely see stuff like this, the single-line "y = 3 b = 4" is
valid syntax in Lua). By contrast, with NetLinx, it's always clear at a
glance where a statement ends if the code is formatted well.

Again I will state that if it isn't clear where a statement ends, there is
a problem with how a statement is written. Semicolons will, at most, mask
that issue. I know others here are used to semicolon terminators in other
languages, as I am. This is a place where a preference to see something
because we're used to seeing it somewhere else doesn't add anything at all.

[amx-netli...@googlecode.com]

Comment by jordevorstenbosch:

True, they do nothing for the program indeed, but they do for us.
Nonetheless, I guess it's a preferred way for people here. Jeff doesn't
seem to mind and kim doesn't at all. So I'll go along with you guys and
we'll do without semicolons.

Btw do you use LUA for vantage systems?

[Kim]

Cool.

So it looks like we've come to a (sort of) agreement, at least for
now. If we find that the omission of semi-colon's is hindering
readability in the future we can revisit the issue.

I'll try and get in today and format, name and layout everything to
the spec in it's current form. Before I do I'll give everyone one more
chance to "speak now, or forever hold your piece" :) . Once that is
done we can run everything through some unit tests (if someone wants
to put this together that would be awesome, otherwise I should get a
chance this week) fix any issue's we find and put together a 1.0
release.

[amx-netli...@googlecode.com]

Comment by kim.john.burgess:

Right, sorry to revive the 4 vs 8 character tab stop debate but one thing
I've been noticing since switching to 4 characters is the majority of code
review tools utilize 8 characters by default. A lot of them let you select
an arbitrary (or at least 4/8 character) tab width however ones that don't
are set to 8. To help with the original goal of sticking as closely as
possible to the linux kernel style guidelines what are peoples thoughts on
reverting to 8?

[amx-netli...@googlecode.com]

Comment by trueamx:

I'm against it.

What tools are giving you grief?

[amx-netli...@googlecode.com]

Comment by trueamx:

I'm against the idea of event handlers having braces placed below the event
handler line, as in function calls. Any control structures - whether it is
an event handler, select..active, switch..case, if, while, for - should all
have the brace on the same line.

Is there a reason for having it the way currently described?

[amx-netli...@googlecode.com]

Comment by feddex:

I'd just like to say, this is a fine guideline, but I must confess I don't
agree with a few things I see here.

Why in conditionals, arrays and loops would you put the open curly brace on
the same line as the original statement, and then in define functions/calls
and event handlers put it on a separate line? Is there something intrinsic
about them that would steer one away from using a universally defined
convention? I prefer to put the open curly brace on a separate line always,
and it makes it easier to read someone else's code when they do the same.
This is a style question that has been brought up in the forums, and AMX is
apparently now teaching in their classes to universally put the opening and
closing braces on their own lines.

Also I use a wide screen display and I prefer to use 2 space tab stops. I
actually save my preferences on an external drive so when I get a different
laptop (which I do from time to time), I update the preferences to that. I
just think it looks more compact. I also use Consolas 12pt font so that
may make the difference.

Overall though I like the thought of this. I'll pop in from time to time
to see what's going on here.

[amx-netli...@googlecode.com]

Comment by trueamx:

feddex,

The guideline for function braces is part of the Linux guidelines we are
basing ours on. It also makes some sense, since function prototypes can be
quite long for parameters and it makes it a bit easier to differentiate the
prototype from the code.

I do not agree with event handlers doing this. This was just added to the
wiki this way but probably shouldn't be followed and the wiki should be
changed (it seems to be Kim's baby - should I change this?) Where I am
using event handlers, I am currently using them in the same way as
everything else and not as described in the wiki.

The brace style is preferential, but we've basically settled on what we
have now. AMX also teaches people to prefix functions with fn, to
incorrectly use hungarian notation, and that include files need to be
compiled; we should look at other, external successful projects using
similar procedural languages for influence rather than AMX CAPSLOCK
training guidelines. Consequently, we based our style off of the Linux
style guidelines and tweaked it mostly for the language, and partially for
group preference.

I sometimes use 2spaces/tab but it can get hard to read. 8/80 means less
tabs, which can affect same line comments amongst other things. I think
4/80 is a good compromise. I use a wide screen, high res display as well
and would prefer 120wide, but not everyone has one and agrees with this
respectively and I've dropped my argument for now. (I use an even smaller
font - DejaVu Mono at 8pt or 9pt, on a 150ppi monitor.)

I don't agree with everything here either, but it's quite fine and usable
so far, and mirrors what much of the professional software development
world uses. Even if you use these libraries, the rest of your code can be
written however you want ;)

[amx-netli...@googlecode.com]

Comment by kim.john.burgess:

The event handler bracing rules were just added to get mention of them in
the guideline, as these are something that is unique(ish) to NetLinx. The
guide is far form comprehensive or concrete at this point so if there are
points that anyone wants to discuss this is what these comments and the
mailing list are for (eg. at this point looks as though the general
consensus is line breaks before braces in functions only). Once the
libraries reach level of maturity that will warrant an initial release
they'll become a little more solid.

[amx-netli...@googlecode.com]

Comment by feddex:

Thanks for all of the replies

I understand the need for convention, but shouldn't we allow the
manufacturer and those that have been using the code daily to make a living
to keep the convention for the code as opposed to trying to fit it in the
mold of other codes? If you want it to resemble other code conventions,
why buck the the trailing semicolon?

No matter. I have gotten used to the way I code, and I prefer it. But if
I submit something, I'll try to adhere to the convention. And FWIW, I HATE
Hungarian Notation.

Nifty digs here, I may just pop in from time to time.

[amx-netli...@googlecode.com]

Comment by jordevorstenbosch:

Changed the column width to 81 characters, noticed that it includes the
code-folding section as 1 character, so setting it to 81 actually gives you
80.