Saturday, 14 October, 2017 UTC
Summary
The following is a short extract from our book, Jump Start Sass, written by Hugo Giraudel and Miriam Suzanne. It's the ultimate beginner's guide to Sass. SitePoint Premium members get access with their membership, or you can buy a copy in stores worldwide.
Clean, beautiful code should be a goal in every project. If other developers need to make a change, they should be able to read what is there and understand it. Readable code is the core of maintainability, and the first step towards readable code is a good linter. Like a good spell-checker, the linter should catch all your small typos and formatting mistakes, so it’s not left to others to do so. It’s the first line of defense before a good code review with other developers.
There are several great linters for Sass: scss-lint is a Ruby gem, and the newer sasslint and stylelint, which are npm packages for Node. Both allow you to configure linting rules for your project, such as maximum nesting levels, leading zeros on decimals, and organization of properties in a block. You can even create your own rules as needed.
Sass Guidelines are handy for organizing your project, setting up your linters, establishing naming conventions, and so on. Written by Hugo, it’s an opinionated styleguide for your code; it might not all work for you, but it’s a great place to start.
If you’re using Sass variables, functions, and mixins, it’s recommended that you document how they work. Toolkit authors will find it particularly important, but anyone who has extensive tooling built into their projects should also consider documentation for their team. Another great tool from Hugo is SassDoc, an npm package that parses your Sass comments and generates a beautiful static site with your documentation.
Here’s the SassDoc comment for our
tint(..) function in Accoutrement-Colors. It starts with a general description, and then explicitly documents each parameter and the expected return: /// Mix a color with `white` to get a lighter tint.
///
/// @param {String | list} $color -
/// The name of a color in your palette,
/// with optional adjustments in the form of `(<function-name>:<args>)`.
/// @param {Percentage} $percentage -
/// The percentage of white to mix in.
/// Higher percentages will result in a lighter tint.
///
/// @return {Color} -
/// A calculated css-ready color-value based on your global color palette.
@function tint(
$color,
$percentage
) {
/* … */
}
Using the default theme (from which there are several to choose, or you can design your own), SassDoc converts that comment into a static website, as shown below.
Continue reading %How to Write Beautiful Sass%