User Tools

Site Tools


soft:server-design

Design, Structure and Coding of the Server Software

Framework

The Server is based on Django framework, a high-level Python Web framework. The reasons that has led us base our development on this framework are:

  • Fast development and clean design
  • Comprehensive documentation
  • Automatic admin interface
  • Background with the framework

A more detailed discussion of the options can be found here.

Applications

Each piece of functionality is split into different applications. An app should be focused and follow the Unix philosophy of “do one thing and do it well”. In other words, an application encapsulates some particular feature. If this sounds new to you, maybe you're interested in this talk.

Common/Generic code

  • When a piece of code is considered generic or can be used in different applications it should live on the main controller application.
  • All images/code/files that are Confine related should live on the controller module.

Modules

Following the Python modules that you can expect to find inside each application:

Core

Admin

  • fields.py Model and Form Fields.
  • forms.py Django forms.
  • widgets.py Forms widgets.

REST API

Other

  • ifaces.py Sliver network interface definitions.
  • notifications.py: pluggable notification system based on server-apps-notifications notification app.
  • tasks.py: Celery tasks (Celery is an asynchronous task queue/job queue based on distributed message passing).
  • utils.py Functions that do one repetitive and specific thing.
  • helpers.py Functions that are part of other functions, in contrast with utils, helpers functions are highly coupled with their parent and do not have context other than that.
  • validators.py Django validators.

Reusabilty

Apart from the ovbious benefit for others because of being able to reuse our software, writing code with reusability in mind also helps to keep the code structure clean and modular. Keep this in mind:

  • Any component can be relpaced in any moment (apps)
  • Constant parameters can change over time (settings)
  • Each single component should be able to be reused on other projects (apps)

These are ideal states, be pragmatic above all :)

Well known related design principles:

Advanced tutorial: How to write reusable apps

Conventions and best practices

Some online resources that can be worth reading

Django

Python

Coding Style

Development Workflow

Common Theme

In general try to write as less code as possible. And remember Don't repeat yourself, Keep it simple! and Repair broken windows!

Be careful choosing class, function and variable names: be descriptive and avoid abbreviations if they aren't clear (characters are almost free :)

Naming convention:

  • class: SingularName
  • action function: verb_name() (validate_user(), get_whatever(), make_something())
  • boolean function: has_something() (has_permission(), has_blue_eyes())
  • date attributes: attribute_on (deleted_on)
  • boolean attributes: is_something, allow_something (is_active, allow_slices)
  • properties: like if they where attributes

If your code needs to be commented maybe is because it is too complex, give it a second thought!

Readings that you might find interesting:

  • Code Complete (2nd edition) by Steve McConnell
  • The Pragmatic Programmer
  • Clean Code: A Handbook of Agile Software Craftsmanship by Robert C. Martin
  • and more
soft/server-design.txt · Last modified: 2015/06/17 16:15 by santiago