Create a coding style guide

[jungshadow]

I'm wondering if we should follow the 1622.2 style guide. I mentioned this in a separate comment to @pstenbjorn a while back. If I were to break them out as a guess:

• attributes seem to be camel-cased (NB: exception being object_id),
• elements seem to be title-cased with no separators, and
• enumerations seem to be lower-cased with hyphens taking the place of spaces.

It would mean a lot of changes, but it would be nice to have an agreed-upon coding convention and a bit more similarity between the two specs, especially as we're planning to consume the ballot models. If everyone agrees, I'll create a pull request with the brief "style guide."

[pstenbjorn]

@jungshadow for readability I agree that following a consistent style is reasonable and if we are going to seek interoperability with 1622.2 it would be best to have consistent styles.

[cjerdonek]

I would also like to make a plug for using standard line endings (see for example here and here on how to configure git, etc). The files seem to have \r\n line endings while \n plays nicer with Git.

[demcg]

Yes, a style guide makes it easier to maintain code/documents.

[jungshadow]

@cjerdonek Knowing that @pstenbjorn uses a Windows machine to do most of his work and I'm on a Mac, I personally haven't experienced any issues. Are you encountering issues with the files?

[cjerdonek]

Are you encountering issues with the files?

@jungshadow Yes, in that git is flagging any changed lines that don't end in a single newline \n (e.g. when using git-diff or git-log -- see a sample screenshot below). Git has a setting to normalize files to end in a single newline \n (to make things easier for projects having both Windows and Mac OS X committers), but it only works if the files are standardized to end in newlines to begin with.

[cjerdonek]

Here is one of the better descriptions of the problem and solution:

core.autocrlf

If you’re programming on Windows and working with people who are not (or vice-versa), you’ll probably run into line-ending issues at some point. This is because Windows uses both a carriage-return character and a linefeed character for newlines in its files, whereas Mac and Linux systems use only the linefeed character. This is a subtle but incredibly annoying fact of cross-platform work; many editors on Windows silently replace existing LF-style line endings with CRLF, or insert both line-ending characters when the user hits the enter key.

Git can handle this by auto-converting CRLF line endings into LF when you add a file to the index, and vice versa when it checks out code onto your filesystem. You can turn on this functionality with the core.autocrlf setting. ...

[cjerdonek]

I checked the line endings of the top-level files in the master branch, and this is what I found:

CRLF: index.html
  LF: README.mdown
CRLF: sample feed for v2.1.xml
CRLF: sample feed for v2.2.xml
CRLF: sample feed for v2.3.xml
CRLF: sample feed for v3.0.xml
CRLF: sample_feed_for_v4.0.xml
  LF: sample_feed_for_v5.0.xml
CRLF: spec_v2.2_documentation.html
  LF: vip_spec.xsd
  LF: vip_spec_pending.xsd
CRLF: vip_spec_v2.1.xsd
CRLF: vip_spec_v2.2.xsd
CRLF: vip_spec_v2.3.xsd
CRLF: vip_spec_v2.3_documentation.html
CRLF: vip_spec_v3.0.xsd
CRLF: vip_spec_v3.0_documentation.html
CRLF: vip_spec_v4.0.xsd
CRLF: vip_spec_v4.1.xsd
CRLF: vip_spec_v5.0.xsd

Also, sample_feed_for_v5.0.xml seems to be encoded in UTF-16, as opposed to UTF-8 like all the others.

[jungshadow]

@cjerdonek Sounds doable. I'll add a .gitattributes file to the vip5 branch and add a separate issue for that particular update. That said, since we'll have a .gitattributes file that enforces LF endings, I don't think it's worth mentioning it in the coding style guide.

[cjerdonek]

@jungshadow awesome, thanks!

[cjerdonek]

A few other conventions that I noticed would be useful for a style guide:

• all files encoded in utf-8
• spaces instead of tabs (or vice versa)
• no trailing white space at the end of lines

[demcg]

Can we add a section on attribute ordering in XSD? something like:

1. name
2. type
3. minOccurs
4. maxOccurs

If this is deemed a good idea, I can refactor the current XSD when most of the pull requests have been merged. This will avoid merge conflicts.

[demcg]

I collected the suggestions from this issue into StyleGuide.mdown on the branch feature/StyleGuide.

@cjerdonek - The spaces vs tabs issue is still open, however to get going, I suggested 4 spaces to the tab.

[cjerdonek]

@demcg Great!

Re: tabs vs spaces, yes, I think four spaces is more common. FWIW, all projects I have been involved with have preferred four spaces. I believe that is also git's default.

Re: attributes, I would clarify that you mean attribute names as opposed to attribute values. Also, I think "snake_case" across the board makes more sense for attribute names (e.g. office_id as opposed to officeID or officeId), as opposed to having different naming conventions for different types of attributes (e.g. with or without "ID"). This also parallels Python's naming conventions, where class names are CamelCase with a leading capital, and method, function, and attribute names are snake case. Either way, I think it would be an important feature that all attribute names follow the same rule.

Can you make a PR for this?