Software Challenge : Styleguide / allgemeine Richtlinien

This page last changed on Jun 18, 2015 by svk.

Ruby & Rails

Niemals *_url oder *_path Route-Helper benutzen. Immer Array-Style ([:method, model1, model2]). Siehe Rails route helpers are brittle.

Niemals eigene HTML <a>-Tags benutzen, immer link_to (link_to "text", model geht auch, sonst link_to "text", url_for(..,)).

Neue Hash-Style Notation benutzen (key: value statt :key => value)

HTTP / REST

POST requests (oder PUT, DELETE, PATCH...) fuer Dinge benutzen, die Daten veraendern. GET-Requests sollten immer dasselbe liefern wenn sie mehrfach hintereinander aufgerufen werden. button_to fuer logout z.B.. Siehe http://code.tutsplus.com/tutorials/a-beginners-guide-to-http-and-rest--net-16340 und http://restcookbook.com/HTTP%20Methods/put-vs-post/

Views / Frontend

JQuery UI wird von der alten Anwendung benutzt, das sollten wir aber komplett durch die Bootstrap-Elemente ersetzen.

Alle Views sollten in HAML konvertiert werden (bisher war das Format ERB). Es gibt ein Ruby-Script welches eine solche Konvertierung automatisch vornimmt: https://github.com/haml/html2haml, weiterhin gibt es diverse Online-Konvertierer.

Immer semantische CSS-Klassen benutzen: http://www.w3.org/QA/Tips/goodclassnames Hierbei ist zu beachten, dass die direkte Verwendung der Bootstrap-Klassen ebenfalls vermieden werden sollte, da diese ebenfalls oft das tatsaechliche Aussehen anstatt der Semantik beschreiben (z.B. navbar-right): http://ruby.bvision.com/blog/please-stop-embedding-bootstrap-classes-in-your-html

Icons

Wir benutzen SVG-Icons, genauer das Evil-Icons Set.

In den Views kann ein Icon mit dem Icon-Helper eingebunden werden:

= evil_icon 'ei-search'
= evil_icon 'ei-arrow-right', size: :m
= evil_icon 'ei-envelope', size: :l, class: "custom-class"

Eine Uebersicht der Verfuegbaren Icons und deren Namen gibt es auf http://evil-icons.io/

Derzeit koennen auch noch Glyphicons (der Standard von Bootstrap) verwendet werden:

span.glyphicon.glyphicon-iconname

Liste der Glyphicon-Namen: http://getbootstrap.com/components/#glyphicons

Allerdings sollten die Evil-Icons bevorzugt werden, da SVG inzwischen nur noch Vorteile gegenueber Font-Icons hat.

JS & CSS Assets: Bower bzw. Rails Assets

Zur Verwaltung von externen Javascript und CSS Abhaengigkeiten sollte in Zukunft Bower verwendet werden. Damit wir kein komplettes nodejs, npm, bower tooling brauchen, bietet sich Rails Assets an: https://rails-assets.org/

  1. Namen des Paketes auf https://rails-assets.org suchen
  2. gem rails-assets-PAKETNAME in Gemfile eintragen (im source "https://rails-assets.org" do Block)
  3. @import "PAKETNAME" in app/assets/stylesheets/application.css.sass eintragen
  4. //= require PAKETNAME in app/assets/javascript/application.js eintragen

Achtung! In Punkt 3 und 4 kann es auch sein, dass man andere Namen verwenden muss, das haengt vom Paket ab. Die CSS/SCSS/JS Dateien sind jedenfalls zugreifbar, als wuerden sie in app/assets liegen. D.h. wenn man eine "foo/bar/baz.css" Datei laut Paketbeschreibung includen soll, kann man den Pfad genauso aber ohne das .css in application.css.sass eintragen.