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. http://jamesgolick.com/2008/1/14/taking-style-tips-from-natural-language

Comments

Popular posts from this blog

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. …

Beginning Erlang for Ruby Developers

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

https://beg-erlang-for-ruby-devs.herokuapp.com/




Improving Traditional Software Development Education

I read Corey Haines post about his idea for software development school. I thought I'd jot down some of my experiences while I taught software development.
I taught community college computer science and web development for 7 years. In the summers I worked as a contractor to gain 'real-world' experience. This allowed me to teach what I learned over the summers in the classroom. Towards the last couple of years of teaching I worked at nights while I was teaching because I enjoyed it so much.
To me I saw a lot of teachers take the easy road: picking canned curriculum that laid out non-practical material, have a work study student grade for them, etc. while they go home early. This was frustrating to watch and be around!! I picked industry books (PragProg, Addison-Wesley, etc.) and used them for reference while I created custom curriculum every quarter because of technology changes. I did not picked canned textbooks. They drove me nuts being out of date and out of touch…