Home

Development guidelines wiki

In progress.

What we use

• The Twitter bootstrap
• Less.js
• jQuery
• Django
• Git for tracking wiki content
• Markdown for formatting wiki content

More info on each to come.

Project layout and structure

Or, How It All Works.

We followed the Django-CMS project layout I think? Same basic idea. More to come.

Coding style conventions

For the most part, we try to follow PEP 8. There are a few notable exceptions:

• We use tabs, not spaces. This is a semi-arbitrary choice enforced by the lead developer because gedit doesn't do spaces that well (at least, there's no way to delete 4 spaces at once that she knows of) and another project she works on requires tabs. (It's just easier to use gedit than vim because of all the files this project has.) We may change to using spaces later on, in which case a huge tab-to-space commit will follow. Sorry for the inconvenience.
• We don't put two spaces after a sentence-ending period in comments. We just don't. None of us are old enough to remember typewriters anyway.

Some project-specific conventions:

• When rendering a view, use render() as opposed to render_to_request. There are several reasons for this, most of which are forgotten but which may have to do with csrf_token and accessing the user from the template. It's also preferred that the data passed to the template (if any) is stored in a dictionary called, surprisingly enough, data. (Sometimes locals() is used due to laziness, but if there's more than one variable to pass then data is preferred.)
• Aim for consistency and avoid code repetition whenever possible. Keep things logical and make relationships clear through the way the code is organised (for example, if a utility function would make sense as an instance method on a class, make it one). Cleanless and keeping code as short as possible (without forsaking readability or maintainability) are important. (A lot of the existing codebase needs to be modified to adhere to these principles - if you want to tackle that, please, do.)
• Avoid doing from some_module import *, especially for more than one import within a module, because that makes it difficult to track where things are coming from and unlike Ruby, Python actually has a decent file-based namespace system. (Still love you Ruby <3) The only exception is in files like __init__.py for models; see the project layout section below for an explanation of this.
• Use xrange() over range() in for loops. We're not aiming for Python 3 compatibility and unless you actually need to store the list of numbers in memory there's no need to use range().
• Use join() when creating strings out of lists. Usage example: ', '.join(['apple', 'orange', 'mudkip']) would give 'apple, orange, mudkip'
• XHTML over HTML, please. So no tags like <br> or <P>lol</P> or, god forbid, <P aLign=center><FONT FACE="Comic Sans MS" size=100>lol</FONT><P ><BR><P bgColor=blue>lololol</P> (which, incidentally, renders perfectly fine in a browser in all its Comic Sans glory).

Some basic rules, using examples from the codebase:

• There should be enough whitespace, but not too much: courses = Course.objects.all() over courses=Course.objects.all() (except for keyword arguments) and login(request, user) over login(request,user), but avoid get_date_x_days_ago( int( num_days ) ).
• Only use parentheses within conditionals and the like if they're necessary to indicate precedence, and avoid explicit usage of True or False: if not show_all: over if (show_all == False):
• Use descriptive names wherever possible, except perhaps in simple for loops: num_sections over x but for i in xrange(1, num_sections + 1): is okay (maybe).

Working with Git

Contributing code using Git is simple. Steps:

• Fork us.
• Pull from your fork and make some changes. (See the issue tracker for ideas.)
• Commit your changes (see this post for tips on writing good commit messages). Feel free to go wild with feature branches and rebases.
• Keep your fork up to date, and submit a pull request when you're ready. For now, there's only a single branch (master) to integrate with but eventually there will be a development branch and possibly feature branches as well. Try to keep the pull request limited to the commits you've added.
• Wait for us to merge your pull request. Try to ensure that it is well-formatted and will result in a clean merge.

If you just want to check out the source code or don't have an account on Github, you can clone the repository with git clone git://github.com/dellsystem/wikinotes.git.

---