Doing Things Better

What does “doing things better” mean? Its a question you might ask. It means that just because something works, doesn’t mean its right. It means that you should be open to change. It means that, in the end, we are never perfect and can always improve.

Not Invented Here, Not Written By Me, and Reinventing The Wheel

Not invented here and not written by me are both driving factors in reinventing the wheel when developing software.

We limit ourselves if we do not build upon the achievements of others. – Chad Dotson

Not Invented Here

I’m sure everyone has encountered developers that would prefer to implement everything themselves instead of using a library.  An example would be not using jQuery or underscore (or comparable libraries) on a web project.

This is a serious problem for several reasons.

  • It needlessly increases development time.
  • It potentially leads to less robust code and/or increased testing time.
  • It potentially leads to less maintainable code.

I’m not saying that libraries should always be preferred over your own code, but they should be strongly considered.  If you choose to re-implement what a library gives you, you should prepare some defensible reasons for not going with the library.

More: Wikipedia

Not Written by Me

This is a more refined, narrower case of Not Invented Here.  Those developers who don’t want to spend the time or have difficulty understanding code written by others often reimplement code because they view it as the simpler solution.  This is a falsity and they hurt their overall code quality and momentum for it.

Some common things you will hear are:

  • I don’t know what that code does.
  • I would spend a shorter amount of time rewriting it.  (Which is most likely a falsehood.)

The Core of the Issue

As I’ve said, I think the core of the issue is that we find it harder to understand what someone else writes vs what we write ourselves.  We must apply programming best practices and resist the urge to reimplement the past.  To grow, we must push past our tendencies and continue to move forward to bigger and better things.

Posted by Chad Dotson in Doing Things Better, Key Concepts, Programming, Software Engineering, 0 comments

Decisions in 1 Pomodori

All programmers suffer from analysis paralysis at some point in their career.  The trick is bringing it to a swift conclusion.  Try this to move forward next time.  Give yourself 1 pomorodi (25 minutes) to analyze the problem.  After that make a decision and go with it.  Whatever falls out is whatever falls out.  At least you were not over-analyzing the problem and getting nowhere.

Posted by Chad Dotson in Doing Things Better, Misc, Programming, 0 comments

A Better AsyncTestCase for Python

If you need asynchronous support in python unit tests, there are a few possibilities.  A simple google search points you to a few packages, one being tornado.  Tornado’s tornado.testing.AsyncTestCase seems straight-forward.  However it does have a shortcoming: it’s not thread-safe.  Trying to use it with a thread will result in a sporadic exception.  Consider this thread-safe, functionally similar alternative.

 

 

 

Posted by Chad Dotson in Doing Things Better, Programming, 0 comments

Automating Pylint with Gulp.js

Automating Pylint (and other Python Tasks) can be achieved with several viable python-based methods, but what if we used Gulp.js?  The following code snippet gathers runs Pylint on the set of python files defined by pySource.

Notes:

  • This is just a first cut.  I may find a better way.
  • I am aware that I could have simply used gulp-shell to call pylint with a collection of directories.
  • I am open to feedback on this.  Let me know if I’m doing something wrong or inefficient.
Posted by Chad Dotson in Doing Things Better, Software Engineering, Tips, 0 comments

No Comments – A Failure Twice

Everyone that writes code has encountered or written their fair share of undocumented code.

A failure twice?

I was encouraged to write this article because of something I read about the pinball game that once was included with windows.  According to the article on MSDN, the pinball game was removed due to a bug that should have been fixable.  However, the overall qualify of the code made repair impossible and the game was removed from the distribution.  Two major items can be taken from this:

  • Failure 1: The could should have been self-documenting / few comments required.
  • Failure 2: Code not easily understood should have been commented.

Properly commented code can be tricky!

In college they push you to comment your code while not stressing that over documentation is also bad.  I remember writing programs that had comments on almost every line for assignments.  In the end it doesn’t buy you anything, it just restates the obvious and clutters the solution.  In the workplace, comments and whether or not the code needs them are hit and miss.

Some notes about comments:

  • Many comments are an acknowledgement of your failure to communicate.  Write better self-documenting code.
  • Outdated or wrong comments are worse than no comments.
  • Consider refactoring code that’s not self-documenting.  I find one of the biggest places this can be done is extracting methods from if statements.
  • Choose a good, descriptive names.  I’m a little wordy in my names, but in the end most of my code can almost read like a sentence.

Remember

The code is your best documentation.  Think about what you want to communicate with it and how to be as clear as possible.

Posted by Chad Dotson in Doing Things Better, Programming, Software Engineering, Tips, 0 comments

Knowing When You’ve Wrote Crappy Code

Note: This article was kicked off by one I read over at LosTechies.

We write lots of code, statistically speaking some of it is what we’d deem as “crappy.” If you’re doing things right and progressing in your career and your understanding; your definition of “crappy code” should change over time.  This is very important concept for a good Software Engineer, its one of the ways we get better.  We recognize our past coding mistakes and work to better them.

Dangers of Crappy Code:

  • It could hide technical debt.  “I don’t really know how or why this works, but here it is. Done.”
  • You’ve not taken the time to make what works, right.  This potentially leads to bloated code, duplication, and an overall poor product quality.
  • Is it robust?
  • It is, potentially, not very reusable.
  • Can I hand this code off to someone else and they understand it?

Preventing Crappy Code:

The prospect of writing crappy code should not prevent you from getting a project working.  However, it is very important to make it as right possible before committing the code changes to the repository.

  • Write self-documenting code.  Some developers may scoff at this statement, but self documenting code is very possible in just about any language.  Remember comments are your failure to communicate.
  • Remember to refactor, refactor, and refactor.
  • Ask for the opinion of a peer.  This should be someone you consider qualified enough to give an opinion.
  • Use “TODO” comments so your thought process is not lost and it will serve as a reminder that you must still make something right.  This doesn’t prevent crappy code from making it into a project but it documents its existence.

What To Do When You Find Crappy Code:

For the sake of this topic, lets assume you run across some crappy code 2 years into maintenance of a software product.

  • Identify why it is “crappy.”
  • Does it work or has it unknowingly introduced bugs into the system?
  • Perhaps leave a NOTE comment in the code, especially if it can add insight into the function of the crappy code.
  • Only change the code if it is within the scope of your current task.  Remember that it has worked for 2 years and changing it now could potentially introduce error.  If you do end up changing the code, attempt to make it right before you finish.  Also make sure to update your unit tests.

Are you Ready?  A Simple Test

Review a code base that you wrote 2 years ago.  Did you find “crappy code?”  The answer should almost certainly be a “Yes.”

 

Posted by Chad Dotson in Doing Things Better, Key Concepts, Programming, Software Engineering, 5 comments

Isolate, Understand, Implement

Isolate, understand, implement: three very important things to remember when adding, modifying or replacing features on a project.  The first step is to isolate the feature.  Hopefully, your project is designed in such a way that once the code is isolated it is in a single place.  The next step is understand.  Meaning understand what the code currently does.  Run the unit tests.  Make sure you know without a doubt why the code works and what the code does.  Also understand any effects that your changes might have.  And finally, implement the new code or changes.  During this phase you’ll modify the unit test set as appropriate, make the necessary changes to the code base, and ensure that the application is stable before pushing it back to your repository.

Posted by Chad Dotson in Doing Things Better, Key Concepts, Programming, Software Engineering, 0 comments

Presentation Is Everything

PRESENTATION IS EVERYTHING

There is something that learned over the past couple of years, presentation is everything. It is quite possibly the most important element in all we do.

Presentation from the aspect of leadership can mean the difference between shared vision and unengaged worker bee. Presentation from the aspect of a product ( in my case software product) means the difference between phenomenal success and utter failure of a product.

In short, no matter how good or revolutionary your product is, if it looks bad, it will fail. To have a physical product example, look no further than the current mobile phone market. Look at two products: one you like and one you hate. What are the specs of each one? Are they comparable or does one have an advantage over the other. Now, for arguments sake, lets say the more “cool” one has a better physical appearance and a more flashy user interface but the one that is less “cool” looking and has a plain user interface has better specs and capabilities, which one would you buy? I’m betting (and society proves) that the “cooler” one with the more flashy interface wins out more than the other device. I’ve got no facts in front of me to prove this directly, only experience and my own beliefs.

FIXING OUR SOFTWARE

So how do we fix our software? Well here are some design concepts to keep in mind.

  1. The API and/or the user interface for software must be intuitive.
  2. The software features must be discoverable. This means that users can learn to use the software by using the software. There is not a need for an involved manual to pick up the software and begin using it.
  3. The software must be easy to use. This is an ambiguous and loaded statement I know, but never-the-less it must be true. Just think about the software you are writing from the user’s perspective.

These are some of my most important concerns for a software product because if a user cannot easily pick up your software and start using it immediately, then you will have problems with adoption within your targeted user base. As with the mobile phone example above; if you have two pieces of software equivalent in terms of capabilities and specs, but one is presented a lot better and is more user friendly, which would you choose?

Going Forward

What we’ve learned here can be summed up in the two following statements. Software must be intuitive, discoverable, and easy to use. Also, presentation and appearance are quite possibly the most important part of software.

Posted by Chad Dotson in Doing Things Better, Featured, Key Concepts, Software Engineering, 0 comments