development.markdown

Development at Hudora

Here we store Information in regard to Software Development at Hudora.

Tools

• We use github.com/hudora for version control (Introduction) - you should create an account there
• We use gerrit as a review system - you should create an account there
• Sublime Text 2 is the offical editor at Hudora Cybernetics.

Coding

• Refactor Mercilessly - your own code and others.
• If you touch a file you are responsible that it is in decent shape afterwards. Even if it was messy before you touched it.
• Your commit messages should be in german or english, use markdown and follow general commit message best practices. Sample: [LH #4711] added abbility to print docs for Swiss customs
• Check the timeline/dashboard regulary to see what's happening. Skimm the changesets and ask if you don't understand something.
• always do make test, make check or equivalent before commit.
• add the URL of the ticket in the ticket system to the end of your commit message
• Work in branches where appropriate. For every feature/ticket a branch may be appropriate.
• Use extensive comments as if you would be writing for docco

Style

• Wrap code at column 109. If you use Textmate type defaults write com.macromates.textmate OakWrapColumns '( 40, 72, 78, 109 )' to make wraping more comfortable.
• Follow PEP 8. Use pep8.py --max-line-length=110 --repeat to verify compliance.
• Follow PEP 257 for docstrings
• No tabs. Not anywhere (except in Makefiles). Always indent with 4 spaces.
• use pyflakes.
• Use pylint. Aim for a score of at least 8. The higher the better. If you score is below 8 be prepared to present a good reason for it.
• Classes/Variables which reference Objects specific to our ERP/our Industry/german trade should be in german as technical terms. Generic Objects should be named in english: "Lieferscheinnummer", "Kundenauftragsnumer", "Rechnung" but "TransportEndpoint" and "DataStore". This line is very blurry. See the "Protokolle" at SoftwareEntwicklung for further guidelines on naming.
• Variable Names should not be abbreviated. The only exceptions are "nummer" -> "nr" and "kommissionier" -> "kommi".
• Code should be targeted at Python 2.7 on FreeBSD / Ubuntu Linux or Google AppEngine
• Functions should be no longer than a screen.
• Helper functions should appear below their parent functions.
• __underscore_methods__() and inner classes should always be defined first within a class.
• Let the Zen of Python guide you and avoid Anti-Idioms.
• Fail Fast and crash early!
• Make your stuff Idempotent.
• Alwais provide audit logs.
• avoid float values where possible. They probably don't work as you think they work. Store Cent instead of Euro, Millimeters instead of Centimeters and so on.
• Provide a Makefile with dependencies, test and check (pylint/pyflakes/pep8) targets.
• Write doctests. Write unittests. Aim for a test coverage of at least 80% for all non-networked code. The higher the better.

Conventions

Use our naming conventions for Adresses, Orders and Warehouse related stuff (more to come).

Identifiers

Use global unique identifiers where ever possible. huTools.luids.guid128() creates somewhat compact representations of random IDs. It's even better if you can find an standartisized Scheme of unique IDs. Good Candidates are found in the EPC Tag Data Standard (TDS), in Tag URIs as defined in RfC 4151. Avoid global counters.

Misc

• you can assume that setuptools, virtualenv, and pip are installed

• Always test Iñtërnâtiônàlizætiøn by putting strange strings into input fields

• Always test <script>alert("XSS");</script> & <bold>Co</bold> by putting strange strings into input fields

• use huTools where appropriate

• Iñtërnâtiônàlizætiøn <script>alert("XSS");</script> %+'"<!-- might be a good test string. Suggested Test Address:

  --!> Müller's & Æeleen's <!-- Rue <script>alert("!");</script> IE-Dublin

Google AppEngine Specifica

• Use filter() instead of GQL - skips the parsing step.
• Use gaetk, instead of Django
• Aim for response time under 1 s better under 500 ms and page sizes under 10 kb.
• Always comment the indexes you add to index.yaml

Tools for internal Developers

• We use [hudora.lighthouseapp.com][lighthouseapp] for feature requests ([Introduction][lighthousintro]) - you should create an account there [lighthouseapp]: http://hudora.lighthouseapp.com [lighthousintro]: https://cybernetics.hudora.biz/intern/wordpress/2009/12/lighthouse-it-is/

Required Reading

• HOWTO Use UTF-8 Throughout Your Web Stack
• Getting unicode right in Python
• The Zen of Python
• Code Like a Pythonista: Idiomatic Python
• Google Python Style Guide
• Refactoring: Improving the Design of Existing Code by Fowler, Beck, Brant, Opdyke, Roberts
• An Illustrated History of Failure (Video)