Skip to content

Latest commit

 

History

History
51 lines (37 loc) · 4.31 KB

DeveloperGuidelines.md

File metadata and controls

51 lines (37 loc) · 4.31 KB
Raw

Basic Guidelines for MarkUs Development

Motivation

MarkUs is mainly developed by Computer Science students who volunteer to work on MarkUs, work on it for course credit or work full-time on MarkUs during their summer break. Whether developers work on Markus full-time or part-time, they usually work on it for one semester (4 months). So since development teams change pretty frequently and the MarkUs code-base grows constantly, it is inevitable for developers to stick to some basic rules in order to maintain or increase code quality.

Development Process: DOs and DON'Ts

When developing MarkUs these are usually the steps you should do (This is important!):

  1. Use Rails tools (such as generators_) when appropriate in order to have code-stubs generated and for migrations_
  2. Write tests
  3. Write code (and document it adequately)
  4. Check if your code is working
  5. Read some Rails documentation which might be relevant for your code (if you are new to Rails)
  6. Go over your code and check if there is a "Rails" way of doing it (If you are constructing AJAX calls by hand you are doing something wrong!)
  7. Put your new code up for review (Do not commit it until your code has been peer-reviewed)
  8. Let your peers know that you have put up a new review request (optional)
  9. Once you got your "ship it", commit your code

DOs

  1. Do use `script/console` (see the Rails command line guide_
  2. Do use the debugger <http://guides.rubyonrails.org/debugging_rails_applications.html>`__
  3. Do use Review Board_ (even for the smallest commit)
  4. Do document your code appropriately. As a rule of thumb provide a brief high-level-description of what your methods do and add comments elsewhere in the code as you find appropriate. You can assume that the reader is familiar with Ruby and Rails. If your code requires more extensive documentation, add a Wiki page describing its functionality (or how to use it). Check "Component Descriptions" section on the Wiki for examples. Remember, once you are done with your work and you leave the project, new developers should be able to use what you have contributed without a lot of effort.
  5. Do ask for help. Ask questions via IRC, email or in person if you can. But don't wait until the next meeting. Often questions can be resolved quickly when another person looks at the code.
  6. Do write unit/functional/integration tests/checks (see Adam's blog post on Rails testing_)

DON'Ts

  1. Don't put the first working version up for review. Go, have a break and come back to your code after a while. Questions you should ask yourself are: Is my controller code really controller code, or should it be moved to a model? Is there a simpler solution? Can Rails help with what I am trying to achieve?
  2. Don't mull over problems alone for hours/days. Sometimes it's better to consult somebody else: two pairs of eyes see more than one :-). Maybe somebody else has had a similar problem, etc. Go ask questions!
  3. Don't fight Rails (it'll beat you). Sometimes Rails' "magic" is irritating. However, you are better off using rather then fighting it :-) Really!
  4. Don't use absolute paths/url's in any code (use url_for instead). Always let Rails generate URLs. You have to assume that there are more than one MarkUs applications running on a server, once deployed. Rails does a really good job on this, so use it.

Code Styleguide

  • Use 2 (two) spaces (instead of tabs) for indenting

  • Make sure you provide a brief and understandable high-level-description of your Rails model/controller code (use RDoc syntax, where appropriate). These high-level descriptions will be part of MarkUs' API documentation (see the MarkUs RDoc API_).

Guides