Code Documentation – before, after, and during coding

christine on November 1, 2018

Sometimes you just need to started on some design for work on a larger ticket or new feature, you want to get your thoughts down and maybe start plotting out a code flow or some potential classes but what app do you reach for?

So much of the time I reach for Google Docs, for my personal or professional work. It’s easy, automatically backs up your work, and makes it very simple to share the document or convert it to another format. Opening a Google Doc, and starting to type out some pseudo code can be frustrating with the automatic capitalization or the code just not displaying as you would like.  I have found the Code Blocks extension extremely awesome with that.  Putting in code next to text is a breeze with it.

Helpful tip – If you are using Google Docs you can change up your preference to not annoyingly capitalize the first letter in a sentence (which is rather annoying for your Ruby classes which like to start with a non-capitalized letter).

Sometimes you just want to work on a spike story or share research that you had to done on a particularly hard debugging process or obscure part of your application. For this type of information, I like the use Confluence, a GitHub readme, or even the GitHub pull request itself. Just depending on if it is something I am currently fixing (it will go in the GitHub PR, preferably with screenshots if it a UI type fix), research for tickets or design coming up (Confluence, so easy to share and searchable for other developers) or if it is something that is needed for the code itself, like metadata or installation information, a readme works well. As a developer, I am trying to improve my git commits and PR for future development and maintenance. I highly ecourage anyone working in Git to check out Tekin Süleyman’s awesome “A Branch in Time” talk. Also his blog post on creating useful git history has some great Git tips and tricks, and really makes you think about how your git comments today, and effect someones code tomorrow.

For UML and flow diagrams, LucidChart, is my current app of choice. It is an online diagramming tool that has a lot of flexibility on what you want to show. Coming up with your flow diagram isn’t too hard, just make use of the typical shapes and lines. For me drawing the lines for the code that is calling a self.method was the hardest, but LucidChart has some pretty good tutorials that can walk you through the process, and help you with all the keyboard shortcuts that make you work life happier.

For the documentation of the code itself, I love writing code that is self documenting. For years with writing Java, if your code needed to have comments above it so other developers could understand what it was doing, it was probably too complicated. Writing comments were not encouraged, and refactoring out methods, and patterns to be better descriptors were the norm. Now with Ruby and the software I develop on, there are more comments in the code base. There doesn’t seem to be any stigma with code comments. Sharing information on how to use a command object, or the usage of an API or providing context on a classes public contract all seem to be valid use cases for inline code comments. I am getting used to using comments effectively in Ruby, and the not bring over any Java stigmas that I might have carried over about comments.  I still do lean towards refactoring out code into smaller chunks with self descriptive method names, but do understand when code comments are helpful. All my method names tend to be more verbose, and I am still working on remembering to snake case everything.

There are so many different things that we have to document as developers that it is so important to figure out the best tools and applications that work for you. So, you as a developer, can document code effectively, efficiently and hopefully in a way that other people can find it and use it. Because the only thing worse than not documenting code is code documentation that isn’t used.

Introduction to OpenStruct

christine on September 7, 2018

Intro to OpenStruct

Last week I had a task to start working with some CSV data pulled in from the database.  There was already existing code working with the data, so I needed to make sure whatever changes were applied, that they were backwards compatible.  The data was an csv representation of an array.  The current code was hard coded to go through the array in a fairly rigid process, so to add some flexibility, and allow better access the data in a controller, it was suggested to use OpenStruct.

First a quick overview on what is OpenStruct, it is a data structure that is similar to a hashe. It applies arbitrary attributes with accompanying values. It seems like magic, but it is just Ruby’s metaprogramming and it defines the methods on the classes themselves. A basic example of using OpenStruct on an object might be:

require "ostruct"

candy = OpenStruct.new
candy.name = "Snickers"
candy.type  = "Chocolate"
candy.amount = 5

Then if I needed to call and figure out the candy name, or type, I can call a method on the object itself (instead of having to do the Ruby hash way which would’ve been candy[:name] # => “Snickers”)

candy.name
> "Snickers"
candy.type
> "Chocolate"

So the code went from using:

@csv = CSV.parse(parsed_text)

To the following with OpenStruct:

@csv = CSV.parse(parsed_text, headers: true).map { |row| OpenStruct.new(row.to_h) }

Making use of the csv data now went from:

@list = @csv[1..-1] || []
@count = @list.count

And now:

@list = @csv.map { |row| row.to_h.values } || []
@count = @csv.count

Accessing the values was much easier, but it is important to note with OpenStruct:

  1. It is not performant, which wasn’t something that needed to be kept in mind for this piece of code but if it is something that you do need to keep in mind, go for a hash or struct.
  2. OpenStruct != Struct , struct is similar to a custom created class that you don’t need to initialize or have any attr for. Struct is more performant, OpenStruct more flexible.  Struct has to have the attributes defined, while it is dynamic with OpenStruct.  For the ex. we have name, type and amount but couldn’t add on later an listing for populatarity.
candy = Struct.new(:name, :type, :amount)
snickers = candy.new("Snickers", "Chocolate", 5)

snickers.type 
> "Snickers"

Exploring Ruby IDE Options

christine on July 6, 2018

I have been working in Ruby and Rails a couple weeks now, but I don’t know if I have been entirely happy with any of the editors/IDE that I have worked with.  Coming from a Java background I used Eclipse/Spring Tool Suite for all my development work.  I knew the short cuts, how to browse quickly and easily, and nothing with Ruby yet has felt like it has clicked.

I have spent the most time in VS Code right now, but I keep on finding features that I am yearning for.  Like local code history, code templates, different views… I have been trying out RubyMine for the better part of a week, and it almost feels like too much going on.  I haven’t gotten a good hold on customizing it, and for some reason when I try the hot keys, they never seem to work.  I know I could change up the short-cuts, but that almost seems like cheating to me, it really isn’t learning the new IDE way of doing something but attempting it to be like something it isn’t.

The lead developer I have been pairing with this week is an emacs wizard.  He makes it look effortless and insanely useful.  I think I might have to give that a go, but if it is anything like Vim I know the learning curve will be steep.  If I remember how to exit properly in Vim, it feels like a win. At home on my windows machine I’m just using powershell for a terminal and Atom for a editor.  It’s super simple, and works great for the small coding exercises that I am doing, but would not work in an enterprise level application.