Skip to main content

Code Documentation

There are two ways to communicate what your code does: the code itself and using comments.

Self Documenting Code

Source code should be understandable not because it has comments but because of its elegance and clarity – correct use of variable names, good use of whitespace, good separation of logic, and concise readability. Code will be read hundreds of times and written only a few times. So invest quality time into spelling out names such as fn into firstname. Fight the urge to use cryptic variable names.

Code Comments

Code should have comments however an abundance of comments can be just as bad as too few. Comments should explain why something is done. The code itself already shows what it is done. So commenting on what is done is redundant. Do not use commenting as a substitute for good code. Another way to say that is that if you need to comment code due to its unclarity then maybe you need to rewrite the code to be more clear and remove the comment.

I found this article which is about using natural language in your code to make it more readable.


Popular posts from this blog

Beginning Erlang for Ruby Developers

If you missed my "Beginning Erlang for Ruby Developers" here is a link to the presentation.

Setting up Sinatra and DataMapper on Windows

I use a MacBook Pro for work and pleasure on a day-to-day basis. Recently, I was asked to teach web students at a local high school. These students know html/graphics/flash/etc. The advanced students were ready for some server-side programming and database integration. I wanted the students to be able to get up and going quickly (for motivation reasons) and to create useful apps (using a database). I felt Sinatra to be a great fit for this. I created a Sinatra app for my uncle and his business. It was a joy to work with it and I was able to deploy quickly using Heroku.
My experience of using Sinatra on my Mac was straightforward. Like most things using Ruby and Mac: it just worked. However, I found out the students at the high school use MS Windows. Fortunately, I have a Windows XP virtual machine running in VMWare so I could prepare that way. I used to teach computer science and web development at Spokane Community College and am aware of teaching Ruby in a Windows lab environment. …

AngularJS 101: A Beginner's Tutorial

Below is the PDF article I submitted to Software Developer's Journal for their series they did on AngularJS. It was published in two of their issues: Nov. 15th 2013 - AngularJS, Java and Drupal Tips & Tricks and Nov. 7th 2013 - AngularJS Starter Kit. It's behind a paywall and thus hidden from most of the world. That sucks... which is why I'm posting my article here for all to see.


AngularJS 101: A Beginner's Tutorial

Github code for application built in the tutorial