Feeds:
Posts
Comments

Last year, I attended DDD North. There were a number of interesting talks and I keep meaning to quickly summarise a few of them.

I’ll start with Kevin Boyle’s presentation on using HTML5 to Build Desktop Software.

A growing number of software producers are now using HTML5 and CSS as the UI layer for their desktop applications. Notable examples include Adobe Brackets and Dropbox.

The most obvious way to harness HTML, is simply to embed a web browser control. Unfortunately, this gives the developer no control over the browser used to render the page. Instead, it will depend on the user’s personal setup. This means that you would need to support multiple browsers.

The Chromium Embedded Framework (CEF) offers a potential solution to this problem. CEF is an open source project founded by Marshall Greenblatt in 2008 to develop a Web browser control based on the Google Chromium project. Essentially, the open source core of the Chrome web browser is repackaged as a library to enable you to include it in your own product. This means that if you use Chromium Embedded as your UI layer, a user does not need to have Chrome installed.

CEF supports a range of operating systems and programming languages.

If you are programming in .NET, you will need to install the CefSharp Nuget package. This provides the .NET bindings to CEF. Versions of this package are available for both Windows Forms and WCF applications.

Advantages of this approach include:

  • The ability to reuse the same view for your desktop and web applications.
  • HTML 5 and CSS have a far larger user base. Designers don’t have to ask a developer to change the styling.
  • A vaster toolset and better availability of third-party libraries.
  • Design time data.

Caveats: There is no Microsoft support for CEF. It is still fairly raw. CEF is written in C and C++, and you may find yourself needing to delve into the C++ code in order to fix problems.

CEF cannot be used for mobile applications. However, it takes a similar approach to PhoneGap or Cordova, so you could probably use these to target mobile devices.

Advertisements

complexity-report is a tool for reporting code complexity metrics in JavaScript projects. As a general rule, the more complex the code, the more buggy it is going to be. Therefore, it is a good idea to try to keep your code simple.

complexity-report is a node package which can be installed using the following command:

npm install -g complexity-report

The tool can then be run from the command line. See the complexity-report website for a list of the available options.

The tool currently reports the following metrics for each function:

Line No.
The line number on which the function’s code starts.
Physical SLOC
SLOC stands for “source lines of code”. Physical SLOC is therefore the number of physical lines of code.
Logical SLOC
The number of logical lines of code.
Parameter count
A large number of parameters can indicate that a new object should be created to group them.
Cyclomatic complexity
The number of linearly independent paths through a program’s source code. A high number is bad and generally leads to more bugs. As a rule of thumb, aim to keep the cyclomatic complexity under ten for each function.
Halstead difficulty, volume and effort
The number of bugs (B) increases with difficulty (D), volume (V) and effort (E). Estimates for the number of delivered bugs can be calculated from these metrics as B = E 2/3 / 3000 or B = V / 3000.

In addition, complexity-report also reports an overall figure for:

Maintainability
The maintainability index aims to measure the ease with which the code can be maintained in order to isolate and correct defects, meet new requirements or cope with environmental changes. It is calculated from metrics such as the number of lines of code and Halstead complexity measures.
Aggregate cyclomatic complexity
An attempt at measuring the overall cyclomatic complexity of the code.
Mean parameter count:
The mean number of parameters per function.

Phil Booth gives a good overview of the different types of complexity measured at JSComplexity.org. You also might like to take a look at Wikipedia’s entry on Halstead complexity measures for further details, including how they are calculated.

Kalei Styleguide

This post continues on the theme of CSS documentation and the automatic generation of Style Guides. I have finally got around to taking a look at Kalei Styleguide.

Kalei is a tool developed by Thomas Davis, Luke Brooker and Richard Barret. It generates bootstrap-like documentation for your CSS:

Kalei1

 

Kalei has an advantage over StyleDocco in that it does not require a build step. Instead it runs on an HTTP server and documentation is generated on the fly.

The steps I followed to get it working were quite straightforward:

  • If you don’t already have a Git client, you can download and install one from http://git-scm.com
  • The next step is to clone the git repository git://github.com/thomasdavis/kaleistyleguide.git.
  • Now you need to serve Kalei on an HTTP server. I set up a Kalei website in IIS. Help desk geek has some instructions for how to Install and Setup a Website in IIS8 on Windows 8. You may also need to edit the permissions of the folder in which you have placed Kalei in order to access it.
  • Finally, I edited edit js/config.js to point at my own styles.css

I then opened the website in a browser and started playing around with editing my stylesheet.

Taking inspiration from StyleDocco, Kalei also uses markdown syntax for creating the content. However, the lack of a build step makes Kalei a much nicer tool to work with. You can simply edit your CSS files and directly refresh your browser to view the changes. I can see this speeding up my development time massively, and it takes any hassle out of using the tool. It also ensures that the Style Guide truly is a living style guide, and will never get out of sync with your CSS files.

Kalei produces a menu of headings on the left hand side of the web page. This is a helpful touch and enables you to quickly navigate to the stylesheet or section in which you are interested.

Like StyleDocco, the main part of the page contains the actual example elements and HTML required to generate them. It does not, however, show the associated CSS markup. I didn’t find I particularly missed this though, as it makes for a cleaner UI.

My overall initial impression of StyleDocco is very favourable, and I look forward to using it in more earnest.

StyleDocco

StyleDocco is a tool for the generation of documentation and style guide documents from your CSS stylesheets. It was written by Jacob Rask and is available as a Node package under the MIT license. It includes support for SASS, SCSS, Less and Stylus.

Assuming you have first installed Node.js, you can install StyleDocco globally by simply running:
npm install -fg styledocco

The next stage is to write some stylesheet comments. Later, StyleDocco will be used to parse these comments through Markdown and display them in a generated HTML document.

Markdown converts text with four spaces at the front of each line to code blocks. StyleDocco also supports the GitHub Flavored Markdown convention of wrapping text with fenced blocks (```) to achieve the same effect. Whichever way you choose to do it, you can use this technique to write HTML code in your comments, and StyleDocco will show you a preview with the styles applied, the example HTML code underneath, and the CSS markup next to it. Whitespace before a comment block will ensure it is excluded from the documentation.

Finally, to generate the HTML style guide documents, you will need to run StyleDocco. An example command might be:
styledocco -n "My Project" -o mydocs styles
where "My Project" is the name of your project, mydocs is the name of your output directory and styles is the name of the directory containing your stylesheets.

For example, the following stylesheet:

/* Buttons
==========
Buttons for performing actions in the site.

Identifies the primary action in a set of buttons.

    <button class="btn primary">Primary</button>
*/
.btn.primary {
    background: #0000FF;
    color: #FFFFFF;
    border: 2px outset #000000;
}

/* Identifies the cancel action in a set of buttons.

    <button class="btn cancel">Cancel</button>
*/
.btn.cancel {
    background: #FF0000;
    color: #FFFFFF;
    border: 2px outset #000000;
}

/* News
==========
 Provides extra visual weight and identifies a news article.

    <div class="news">A news article</div> 
*/
div.news {
    background: #FFCC00;
	padding: 5px;
}

 

generates the following styleguide:

kalei2

Each preview includes a drag handle to help you see the effect of re-sizing it. If your project includes a README.md file, it will be used as the base for your index page.

At the bottom of the screen, there are various different options you can click to view it as it might appear on, for example, a smartphone or a laptop.

While I like StyleDocco very much, I have come across a few issues while trying it out in its current state, the first one being most serious:

  • Using IE9 or IE10, the previews are not currently visible. I haven’t yet tried it in earlier versions of IE as I don’t have VMs setup at home, but setting the browser mode to IE7 or IE8 does not resolve the issue.
  • In Chrome, the previews can be resized larger but not smaller.
  • In Firefox, resizing the browser does not resize the previews.

I would not want to introduce StyleDocco in a work environment without first looking at whether I could resolve the Internet Explorer issues.

If I were to introduce StyleDocco in a work environment, I would want to include it as part of the build process. This would enable other developers to view the documentation without necessarily having to set things up on their machine. However simple it is to set up a machine with Node.js and StyleDocco, I have found new ideas less likely to take off, the more obstacles there are to doing them. Also, once it becomes part of the build process, it effectively becomes the standard.

I look forward, next, to taking a look at another tool: Kalei Style guide by Thomas Davis.

There are a number of node modules that can be useful tools when developing JavaScript or CSS.

In order to use one of these tools, you will first need to download and install Node.js.

Once you have installed node.js, any package can be installed by using the node package manager, npm. Any packages that the package depends upon are also automatically installed.

To install the latest version of myPackage for a single project, type the following into the command line:
npm install myPackage

Alternatively, to install the package globally, include the -g option:
npm install -g myPackage

I recently came across a book called CSS Mastery by Andy Budd, Cameron Moll and Simon Collinson. The book introduced me to a couple of new ideas with respect to CSS style sheets.

In recent years, there have been various projects to standardise CSS comments and to extract documentation from these comments.

Cssdoc started out as a CSS commenting convention to help people improve the writing and managing of CSS files.
Inspired by cssdoc, Thomas Kadauke created a Ruby library and command line tool called css_doc. This tool can be used to extract documentation from css files.

The book also discusses the concept of a style guide. A style guide consists of one or more documents or web pages that explain how the code and layout of a site is put together.

Upon further investigation, I discovered that there are now several tools that allow the automatic generation of a style guide from specially formated CSS comments.

Knyle Style Sheets (KSS) is a documentation specification and styleguide format with a ruby library capable of parsing SASS, SCSS and CSS documented using these guidelines.

However, in his talk “Improving your responsive workflow with style guides“, Luke Brooker recommends StyleDocco and KALEI StyleGuide over KSS for the creation of rapid style guides.

StyleDocco is a node package that generates documentation and style guide documents from your stylesheets. Stylesheet comments are parsed through Markdown and displayed in an HTML document. You can write HTML code prefixed with 4 spaces and StyleDocco will create a preview with the styles applied. The CSS markup is also helpfully displayed next to the documentation.

KALEI StyleGuide is another tool that apparently does much the same thing but with the advantage that it does not require a build step. Instead, documentation is generated on the fly using JavaScript. Unlike StyleDocco, it does not display the css markup next to the documentation.

I have started taking a look at StyleDocco. It looks very promising. I also plan to take a look at KALEI StyleGuide and write a blog post about each of them.

While studying for my MCTS, I happened to come across the following invaluable site which gives a list of links to MSDN covering the material for each section: Certification and maybe some other stuff: A blog about Microsoft Certifications and general ASP.NET