Set all our source code conventions. [8h]

[dpinney]

Small Conventions

1. Spaces or tabs? Tabs.
2. Single quotes or double? Single.
3. Module, function, class, etc. names? camelCase for all names. InitialCapsCase for class names.
4. Zero trailing spaces.
5. Every function, module and class needs a docstring inside triple quotes.
6. Remove the #!/bin/python because nobody's running this stuff as shell scripts.
7. Use unicode literals e.g. & # x2192; instead of →.
8. Variable name lengths? Aim for shorter. Do not use uncommon abbreviations. This is tricky and a judgment call. Then document the conventions and clean up the code to match them.
9. Indenting dictionaries or long lists? See longDict below.
10. Nesting functions: try not to do it. This is tricky and a judgment call.

longDict = {
    'item':3,
    'other': {
        'x':3
        'z':2 },
    ...
    'end':6 }

Questions

1. Also, how do we clean up our namespaces? Don't need to show omf.os, omf.subprocess, etc. to dir.
2. Do we use Hungarian notation? E.g. lengthOfBridgeFloat.
3. Should more things be objects? Hard question!

[mhavard999]

I vote spaces and double quotes. Spaces are always the same width, so if it looks nice in your text editor, you can be sure it will look nice to the public on github, which is tricky with tabs. And double quotes are just a personal preference of mine, but also in Emacs' html-mode, single quoted strings are not highlighted as strings. So it would just be convenient for me personally.

[mhavard999]

(3) Naming conventions for functions, classes, etc. Mainly functions because I haven't written any classes, so we would just go with whatever you've been doing. We have a mix of function_name and functionName.

[mhavard999]

For Python, I think double quotes are the standard. The flask repo uses double quotes for docstrings, so we probably should too. Though in this particular file the __version__ is single quoted: https://github.com/mitsuhiko/flask/blob/master/flask/__init__.py

[dpinney]

I prefer tabs. They look fine on github. Double quotes are good. I'm tired of escaping apostrophes in contractions.

[mhavard999]

I also think that using literal Unicode characters, rather than ASCII-escaped equivalents, has to be a bad practice. Example from line 187 of gridEdit.html: we have <li><a href='javascript:history.back()'>Leave →</a></li> instead of <li><a href='javascript:history.back()'>Leave &#x2192;</a></li>, which I feel would be a lot clearer from the programmer's perspective.

[dpinney]

no more literal Unicode characters

Most definitely. Getting encodings to show up correctly across unix/windows/git/emacs/sublime is a pain. Added to the conventions.

[cshjin]

Instead of coding different styles, I suggest use some commonly used coding style, such as google coding style guide, which most people will follow. Hunt for Python Guide, JavaScript guide and HTML/CSS

[dpinney]

Let's aim for PEP8 for most conventions. I like variableNamesInCamelCase instead of variable_names_with_underscores but, hey, we're a python project.

[cshjin]

Do we need to check our code strickly using pep8, such as:

C:\Users\jxh10\Documents\GitHub\omf>pep8 --first web.py
web.py:3:80: E501 line too long (115 > 79 characters)
web.py:7:12: E401 multiple imports on one line
web.py:17:1: E302 expected 2 blank lines, found 1
web.py:18:1: W191 indentation contains tabs
web.py:19:5: E701 multiple statements on one line (colon)
web.py:20:9: E274 tab before keyword
web.py:28:19: E231 missing whitespace after ':'
web.py:28:80: W291 trailing whitespace
web.py:29:3: E128 continuation line under-indented for visual indent
web.py:37:2: E265 block comment should start with '# '
web.py:48:2: E301 expected 1 blank line, found 0
web.py:97:29: E251 unexpected spaces around keyword / parameter equals
web.py:164:1: W293 blank line contains whitespace
web.py:241:10: E225 missing whitespace around operator
web.py:473:35: E272 multiple spaces before keyword

We can also configure it to our own style if we need, Check here configuration

[cshjin]

A fast way to do it using sublime package control to install AutoPEP8, and it is the best package among all those PEP8 formatting packages I found. Go for it AutoPEP8

[dpinney]

Delayed to Q3.

[dpinney]

Platform: audit all the libraries, clean up the interfaces (e.g. treeParser write methods should be toString, etc.). [20h]

[dpinney]

Guide added to wiki.