Blog posts by Geekyboy – Adam Culp

We’ve all done it…opened a file using vi or vim to inspect the contents, and realize we need to alter it.  Of course we totally ignored the message informing we didn’t have permission to edit, so we’re only allowed to view it as “read-only”.  Then after we find the troublesome spot we hit “i” and happily edit the place needing changed, only to “face-palm” when we realize we cannot save the wonderful edit we just made.

In the past I handled this one of three ways: I either copied and pasted the change after reopening the file using sudo, or I reopened and retyped everything once again, or I save the file as a temp file and then rename it using sudo.  Very stupid, stressful and time consuming.

However, now I know a better way.  Using a combination of ‘tee’ and ‘sudo’ commands I can now save the read-only file rather than jumping through the hoops in the previous paragraph.  Here is how:

Open a file as normal, forgetting to use “sudo”, and therefore viewing a read-only file.

Then mistakenly try to edit the read-only file in the traditional manner.

But when we try to save using ‘:w!’, SHIFT+ZZ, or :qw!, or whatever combination we normally fail with as an alternative.  Here is sample output of what we see:

At this point is where the new magic can happen. Instead of the normal “face-palm” we do not “ENTER” and move on. We can enter a new command and successfully save the file after entering the sudo password:

At this point we will be presented with the content of the file and a prompt to press ENTER or type another command. To simply save the file and move on we just press ENTER, and then press the letter “O” (oh). (NOTE: “L” seems to do pretty much the same thing.)  The file will be saved but remains open in vi/vim for more editing or reading.  We can now exit normally by typing “:q!” since the file is still open as “read-only”.

What the command does:

• :w = Write a file.
• !sudo = Call shell sudo command.
• tee = The output of the vi/vim write command is redirected using tee.
• % = Triggers the use of the current filename.
• Simply put, the ‘tee’ command is run as sudo and follows the vi/vim command on the current filename given.

I had the unique opportunity last night to attend a local community meetup where local businesses were brainstorming on how they can attract, and keep, technology professionals to the area.  Years ago Florida made a solid investment in technology when they brought a direct pipe to the Internet through the state.  However, most technology professionals still tend to leave Florida rather than stay.  I live in Boca Raton, Florida and the meeting was held close by, so I decided to attend and see what it was all about.

As most know, I am the organizer of the South Florida PHP Users Group and I am passionate about helping the PHP community grow in south Florida.  Over my years as a developer I have noticed the decline of technology in this market, and specifically the PHP community.  It was this that led me to organize a group dedicated to turning this trend around, and and grow the PHP community rather than continue to watch it decline.

The Meeting

 The meeting started with networking where everyone exchanged business cards and talked, then gathered around a HUGE conference table where the meeting began.  I quietly listened as a new co-working facility was announced, and as the idea of a “computer lab” was brought up as a way to help teach new college students learn things they were not getting in their classes.  Then the conversations gravitated to how local universities were not teaching students everything they needed to know.  The topic of how local businesses should use internships to also teach students “on the job”, then retain them as employees later.  One business owner quickly spoke up and said they did not have the time or money to take on such an endeavor. (Hinting at the true problem in the area, but quickly skipped over.)

The conversations highlighting each persons view of the same topics continued, and anything of real substance was not truly mentioned.  I turned to a fellow developer and said, “They really don’t get it, do they?”  His reply was, “Then tell them.”

After listening to this misdirection for almost an hour I could not take any more, and finally broke my silence.  In my opinion, these are the things that companies can do to attract, and keep, technology professionals. Below is what I covered:

Disclaimer

First, let me state that I realize all companies are not bad.  There are many good companies out there who do treat their developers very well.  I also realize there are companies who pay their developers well, and provide an awesome working environment.  And finally, I realize there are companies who treat their developers as professionals and trust their input rather than using them as a commodity.  I also want to go on the record as saying that south Florida is not unique in how the tech community is mistreated, sadly there are many others.

Also, I realize all people have differences.  Therefore some of my recommendations below might not apply to all.  However, I would assert that my recommendations fit the largest percentage and have been shown to work well with multiple teams I have built and managed.

Working Conditions

Technology professionals need a space with little distractions.  It has been shown that distractions severely hinder professionals because it takes a HUGE amount of time for us to get back into the groove. (some estimates put this number at 20 minutes to get back to where we left off)  So why do companies think it is cool to stuff a bunch of developers into a room sitting around a huge table, or multiple tables, where every movement in the room pulls their eyes away from the screen in distraction?  (So, every time someone moves it causes everyone to loses 20 minutes of productivity.  So how flexible are deadlines?  And how many developers can the company afford?)

Do not mix developers with the general population!  The other staff in the office has no reason to bother developers while they are working.  By not providing a “developer area” it literally cuts productivity in half, or less.

It has also been shown that office workers need their “personal space”.  Not only does this make employees comfortable, but it also allows the employee to “mark” their territory and make it their “home”.  Doing this has been shown to create longevity in employment.  If someone feels at home they are less likely to leave.  Allowing someone to create their space gives a perception of “ownership”, and humans do not leave things they own.

On the other hand developers do like to be able to communicate freely, and having them close together makes sense.  However, I have found that providing a personal space with low (waist high) dividers is wonderful.  It gives developers the personal space they need, and also allows for collaboration when needed/wanted.

Remote or Telecommute Workers

Please do not be alarmed, I am not going to say that all developers should work remote.  However, I think that many are capable of doing it and being more productive as a result.  Many smart companies do tend to stick their developer in a side room somewhere and instruct nobody to talk to them.  (See the Working Conditions section above for tips on how to do this well.)  So, does it really matter if this room is on-location?

Also, if a group of developers desks are put in a room, we notice that very little talking actually happens in the room?  Yet developers seem to “know” what each other is thinking?  This is not voodoo magic.  The developers are regularly communicating through IRC chat or instant messages so they do not disturb each other. (See the Working Conditions section above for why distractions are bad.)  So, if they are communicating without talking or even looking at each other, why do they need to all be in the same place to begin with?

Companies that allow remote working are still able to manage pretty well by having regular meetings, where everyone is required to attend.  This is often used when planning a new project or to relay very important events.  The rest of the time they do not really need developers to be “on location”. (Imagine the money saved for office space!)

Sweat Shop

Most developers actually work around 6 hours per day.  Please do not confuse this to be “Most developers do technology things 6 hours per day”.  That would be a lie.  Developers actually put many more hours into technology each day, but only around 6 of it is actually “work”.  No, just because developers are in front of the computer until 8:00pm does not mean they are getting THAT much work done.  The project will not magically get done faster by keeping developers around longer each day.

Also, please do not fall into the old habits of over-working employees to cut cost.  Forcing a group of 4 developers to regularly work an extra hour or two each day, or God forbid weekends, means another developer hire is needed.  Do not over-work developers.  Adding hours to their schedule does not really get more done, and it will ensure developers leave to work elsewhere.

If you are asking, “What are developers doing after this 6 hours of work each day?”  The answer is probably not as bad as we may think, unless they are not treated well.  Usually they are learning new technologies, or reading blogs and communicating with other developers to keep current, and unfortunately looking for new jobs if they are over-worked regularly.

Future Community Hurt By Moving Too Fast

Many graduates and entry level technology people in south Florida have a very tough time finding a job.  Companies in south Florida, and perhaps everywhere, are moving so fast and have very little money to help grow these entry level folks into a contributing member of the tech community.  To companies who already have a few developers, please augment the team by hiring one entry level person.  Trust me when I say the entry level developer will quickly learn and will be contributing very soon, and may even be the best developer later because they will learn things the “right way”.  Companies will get much more than their money’s worth.

Training (I did not mention this, but should have)

Technology never stands still and is constantly on the march.  New things come out every day, and technology professionals work very hard to keep up with all of this information.  Yet companies do not seem to realize how helping technology professionals learn will inevitably help them.  Companies that help developers learn will benefit.  I am amazed at how many companies will not send their people to developer conferences, or other training events happening.  Not only do these conferences teach new things, but it also allows developers to network and build friendships to help them with problems later.  Then these same companies expect their people to somehow “know” these new things.

On the other hand, if there is a “sales” conference going on, many companies jump at the chance to send as many people as they can.  Then the salespeople re-learn the same techniques and practices that have been taught for decades.  Sales technology has essentially not changed for a very long time.  Seems a little backward, yes?

Respected as professionals

Companies are not professional developers, and many of them have no idea of how to develop.  That is OK, because it is not their expertise, so they hire developers to fill that need.  However, it seems that very few companies actually allow developers to provide their professional advice.  Instead of listening to developers for time estimates, functionality tips, testing requirements, and hardware needs, these things are all ignored to meet some fictional perception the company has for building the application.  Of course the result is typically failure of the application, and ultimately failure of the company or startup as well.

That is kind of like seeing a doctor because we’re sick, or a carpenter to build a house, then telling them how to do their job.

Companies, please respect developers professional advice.  Don’t force them to write bad code to meet unrealistically short time requirements, lack of testing, and poor hardware.  If you hired a professional, let them be one.  Insist they be one.

Salary

I saved this for last because while salary is a concern, it is usually not the largest concern for developers.  If a developer is treated professionally, encouraged/supported to attend training and conferences, not over-worked, and given a nice working environment, they generally are more forgiving of a lower than average salary. (within reason)

Speaking on behalf of developers in south Florida, salary is an issue.  Not only do most companies not follow my recommendations above, but they are also the lowest paying companies in the country for technology related jobs. (By around 10%.)  Meanwhile the cost of living in Florida is among the highest.  This has led many technology students graduating from south Florida universities to leave Florida and go to other areas where salaries are higher.

Now I’m not saying companies in south Florida should immediately start paying 10% more to their developers.  It takes time to make that move.  But perhaps companies should pay less attention to salary when hiring, and focus more on job requirements.  They may find their projects get done faster, better, and more professional because of hiring more qualified developers versus cheaper developers.

Closing

As I found in the meeting I attended, companies do not seem to know how to truly attract technology professionals to the area.  So I decided to help them by writing this post.  Of course there are other things that also help attract technology professional, but if the items I mention in this post are not present then they will not stick around.  We can have the best hackathons, the most awesome coworking spaces, computer labs, and the most funded community events.  But if the developers are not happy at work, they will slowly migrate to areas that offer happy work places.

This past weekend (Dec. 8th, 2013) I had the great opportunity to experience my first Code Retreat in Miami, for the Global Day of Code Retreat, here is a post about it to help inform others about this wonderful event.  If you have a chance in the future to get to one, it is a “must do”.

The Crowd

I was very surprised there was a large group of Rails developers, and it was nice to see there were a few PHP people from the South Florida PHP Users Group (SoFloPHP) because I had posted the event on the group page.  It’s comical how the Rails folks (I do not refer to them as Ruby developers, because generally they do not know Ruby.) seem to feel their framework makes it the best tool for everything, and completely disregard every other language and framework on the planet to blindly evangelize.  I say “blindly” because Rails users seem to feel the need to push the framework on me by selling wonderful features, as if no other language/framework in the world has it.  (But I digress, that is another subject for another post.)

It was nice to see all of the programming languages represented.  There was PHP, Ruby on Rails, Java, Smalltalk, C#, and even some Python.  This made for a nice mix to view other languages, and how developers of those languages operate.

Overall everyone was friendly and it made for a great day of learning and fun.

What is Code Retreat?

Code Retreat is a single day pair-programming workshop giving a chance to practice Test Driven Development (TDD) while trying to solve a pretty challenging sample application, and follow the 4 rules of simple design.  The sample application is to build Conway’s Game of Life.  I will not try to explain the Game of Life here, so if you are curious you can click the link and learn of it on your own.

For many, the sample application is not an easy one to grasp. I found that all of my pairs kept trying to pre-define the game board size at the beginning of the process, though one of the criteria of the game is to have infinite size. (Even the moderator seemed to be stuck on the concept as well, and claimed that predefining a size was OK, because it is how he did it.  I found this disturbing, but overlooked it.)

Others found that forcing ourselves to write the tests first (TDD) was the hardest part of the event, and that is what it was all about.  The event is all about learning TDD, so it was justifiable that it was the challenging part.  I, for one, was up for the challenge and forced myself to NOT WRITE A SINGLE LINE OF CODE WITHOUT A TEST WRITTEN FIRST TO COVER IT.  Because of this I had 100% code coverage the entire day.

The day is broken down into 45 minute sessions where pairs work together and get as far as they can.  Usually the first 5 minutes are spent as each member of the pair explains how they envision the logic to work out.  Following that the initial tests are built to test the game board, then code is written to satisfy the tests.  Then more tests to populate the board, then more code to satisfy tests.  Then tests to makes sure the 4 rules of the game work, then code to carry them out.  Finally, if you got this far, tests to ensure a new turn is executed, and code to satisfy the test.

One of the parts of the interesting parts of the challenge is that prior to each 45 minutes pairing session the pairs were changed.  Which required that the pairs started over by explaining their vision.  Then at the end of each 45 minute session ALL code was deleted to ensure you start from scratch again.  This included any hand-written notes you took during previous pairings.

Of course, due to the 45 minutes restriction I don’t believe that anyone could truly get the completed application running.  But that is OK.  The purpose of the event is achieved by showing the benefits of pair-programming, using TDD (Test Driven Development), and bringing the various communities together.

Additional requirements

In addition to the rules and steps defined above, there was additional criteria placed upon the teams for each iteration.  The first round had no additional criteria, but each additional round carried a new requirement to follow.  For this event we had the following criteria set for each round respectively:

1. Team with someone using a different programming language.
2. 5 lines or less per method/function.
3. No usage of mouse.  All keyboard shortcuts.
4. No talking.

The additional requirements made it fun and forced attendees out of their comfort zone, in most cases.  It was interesting to see how, when faced with the difficulties of the additional requirements, it brought the pairs closer together to tackle the obstacle.

Possible Tweaks

While I did find the event awesome, and enabled developers from across the board to experience new things, I would love to do such an event where everyone used the same technologies.  This would enable to see how other developers in our own area of expertise have adjusted their workflow, and allow further learning.

By having a group using the same technologies it would allow juniors and seniors to learn from each other and grow the individual communities.

My Take-away

For me this was an awesome way to force myself to use TDD to develop.  Too often I get in a hurry and just skip right to the code, then come back and write tests later…maybe.  However, I found that by writing tests first during this event I actually got more coding done and ended up with less code overall.  And it also led me to do less back and forth refactoring during coding, that is normally a HUGE time waster.

I also found that pair-programming was very enjoyable, and led to time savings.  The person at the keyboard tended to get more done while the second person was free to think a bit more, rather than being occupied with the manual tasks of writing the code.

In Closing

I enjoyed the event thoroughly, and would love to do it again….today!  If you get a chance to attend one of these events in the future, I highly recommend it.

Lately I have been talking about clean application development, and how developers can do a better job of it.  Due to the strong focus on this I decided to write some content from my latest talks into a series of blog posts.  Enabling everyone to reap the benefits of the subject matter, and allow attendees of my talks to refresh the content covered at one of the events I spoke at.

In part 1 of this series we discussed reasons for creating dirty code, and the things that dirty code can cause.  We followed with part 2 by giving a possible scenario of how developers get caught in a situation and start writing dirty code.  Then, in part 3 we covered “smells” that hint to dirty code, and some possible situations that can be a bad “smell” highlighting potential problems.  So, what happens when our code carries many of the bad situation covered in the first 3 parts?

Code that made us proud at one time has become an embarrassment we try to hide, and hide from.  In part 2 the developer was very happy with his work in the beginning, and so was his boss.  They were able to complete requests quickly, and everyone was happy to have such fast turn-around on new features.  Then, little by little the problems of the application started to grow.  The bugs began popping out, a change in one place leads to multiple problems in other areas, and time estimates start growing to compensate as the developers are forced to pad them for the unknown. As things become worse the developers tend to care less and less about the code, and this lack of caring shows in newly created code as problems continue to mount.

Many times the first signs of surrender come when the boss asks if hiring more developers will help get things done faster.  It’s an honest question, and makes perfect sense on paper.  If it takes two or three developers six months to create a new feature surely twice as many could do it in half the time.  So the boss instructs us to start a search for more developers to hire, and we spend two or three months (or more) of our “spare” time searching, evaluating, and interviewing candidates until we finally manage to find a couple.  After all, more resources equal more output…right?

Needless to say we go through a few developers, because all of them are not able to grasp the mess we’ve created.  Others just leave for greener pastures rather than try to figure things out.  Then a couple, either due to desperation or being hard workers, manage to stick around and get to work.  But for some strange reason the time-lines never seem to improve, and it still takes a long time to introduce new features.

The boss is very confused, and not happy, because he thought more resources would allow development to get done faster.  He even went to his boss and asked for permission to augment the team, and fought a good fight to get his way.  Meanwhile the developers, seeing the writing on the wall, start scurrying to provide answers for failing to meet expectation.  Technical debt has caught up to them, and it’s time to pay it off.

We talked briefly in part 1 about “technical debt”, and explained it was similar to buying things on credit.  Using credit to buy things means the debt continues to grow and grow, until we’re forced to deal with it.  Either we pay it off, or we go bankrupt and start fresh.  In relation to coding, if we continue to develop poorly taking the “short way”, our technical debt continues to climb with each bad thing we do.  Eventually we find ourselves in a situation where we either repair the code through refactoring, or we rewrite the application entirely and start fresh.

Unfortunately the first reaction to a poorly written application is usually a resounding “rewrite”.  Developers feel like a weight is lifted from their shoulders, as the manager hears a distant “cha-ching” sounds of money slipping away.  The old application took months, maybe even years, to build and cost a HUGE amount of money.  Developers, hosting, tools, sales, customer support, and the hidden costs of insurance/rent/utilities/furniture to keep it all running add up.  In the managers mind a rewrite means it must all be duplicated, and that’s not far from the truth when we consider the salaries of an entire development team for the time it will take to rewrite the whole application.

Challenging sale

In the past there has been times when I inherited an application full of dirty code and recommended a rewrite to the client.  On the surface it seemed like a good idea, and a win/win situation for both me and the client.  It allowed me to make a little more money, because a rewrite take longer than simply doing updates or creating some new functionality.  It also meant I could create the application “my way”.  Because if it was built using my favorite framework, with my coding standards, and unit tests, it would be so much easier for me to work with.

The customer would benefit from a “better” application, pay for less time on future enhancements because it was “better”, and might even get some performance gains with less bugs from the application.  The downside of course is that it costs the customer a much larger sum of money, and much longer time period, to have a rewrite done.

The rewrite

After much debate the developers may eventually win, and the manager will allow the rewrite.  But only if the team is divided so part will be dedicated to building the new vision while the rest will support the old application.  It only makes sense the developers who have been there the longest should develop the new application, since they understand the business better. (Even though they were the ones who created most of the bad code to start with.)  The newly split up developer teams start working.

As the “experienced” team starts the new application the other team continues to fix bugs, and develops new features in the old application.  It happens this way because business must continue to make money and service customers who continually need new functionality, or they will leave.  Which causes endless scope creep for the team developing the new application.  Not only are they attempting to build a new application, but they must also keep pace with new features added to the old application as well as incorporate any bug fixes and/or changes to the business logic.  We start to see how difficult the task of rewriting becomes.

Rewriting started with the best intentions as everything is planned ahead of time, code written in an organized way, and perhaps unit test are even written.  But as time moves on, and the scope continues to creep, the business side of the company starts to become impatient.  The developers start to hear, “Is it done yet?”, and under mounting pressure to speed things up they fall back into the bad practices used in the old application.  Before long the new application starts to suffer the same technical debt issues, and the downward spiral drags on.  Ultimately the developers end up in the same position of apologizing for padded time-lines, unpredictable bugs, and cascading errors.

Usually by the time this entire process plays out there has been a change of developers, and maybe none of the originals are still around.  The current team is now faced with two similar applications that both contain dirty code full of smells, and may not even have tests.  They are now faced with the same choices of the previous team…to rewrite or refactor.  And if they refactor, which application do they refactor?

Meanwhile the company, waiting for the new application, has been dragging its feet on some new features.  Or perhaps have been promising the new application to their customers and building expectation.  This costs the company money in lost revenue from lack of features, lost customers who went elsewhere to get the new features, and higher costs for the extra developers required for a dual-application path.  Eventually, if left unmonitored, companies cannot recover and go out of business from scenarios like this.

Refactor instead

On the other hand, what if we fought the urge to push a rewrite?  If the current application is working and already contains all the business logic needed, but has a very dirty code base, why should the customer endure the loss of time and money for a rewrite?  Plus, if we are new to the application and don’t really know all of the business logic, why should we endure the headaches and heated meetings while we discover every little nuance of a new application.

Now don’t get me wrong.  I realize there are some circumstances where a rewrite is absolutely necessary.  Perhaps the framework the application uses has had a major upgrade, or perhaps the application business logic is undergoing a large overhaul, or maybe the code is just…that…bad!  Yes, there are times a rewrite is inevitable, and simply MUST happen.  What I am introducing here is the idea that many times when we do a rewrite it may have actually been better for the customer, and maybe us as well, if we had simply performed refactoring as we went.

What I have come to realize as a much better solution than the rewrite story above is to follow some of the steps, but take a different turn.  What I mean is that I still split the team up, but rather than instructing one team to build a new application I dub them as the “refactor team”.  Their job is to start refactoring the code one module at a time.  First they write unit tests, if there weren’t any.  Then they start performing scheduled refactors.  Meanwhile the other team starts following the new coding standards and styles, and writing unit tests as they continue to do bug fixes and adding enhancements.

Of course these two teams need to be closely monitored, and must communicate very often to ensure they are not stepping on each other.  IT IS VITAL that everything be managed carefully, and that the teams are communicating open and often.  Did I mention that communication is important, and it must happen often?

Sure there will be times when commits clash, and code will need to be altered using pair programming.  However, the cost of time and money will be greatly reduced from a full rewrite.  Not to mention it will help bring the development team closer together in the process.

After the initial modules are refactored in this manner it may be beneficial to rotate some members around on each team.  This will ensure that team members on both sides of the fence do not become bored, or fall into bad habits.

In closing

Remember, I am not saying one way is better than another in every circumstance.  It’s really a judgement call on which method is used to deal with the technical debt of the application we are working on.  However, I hope this post has helped highlight that a rewrite is not always the best solution.  Sometimes the best approach is to plan a series of refactors to recover the application from the junk pile.  We must carefully analyze the entire picture and determine if a rewrite is a “must”, or is it a “nice to have”.  Then we can honestly create a full list of pros and cons to more fully gain the big picture, and use that list to sell what we believe to be the best solution.

It may very well save the company from being a “used to be”, and instead make it a “will be”.

Lately I have been talking about clean application development, and how developers can do a better job of it.  Due to the strong focus on this I decided to write some content from my latest talks into a series of blog posts.  Enabling everyone to reap the benefits of the subject matter, and allow attendees of my talks to refresh the content covered at one of the events I spoke at.

In part 1 of this series we discussed some causes of dirty code, and then talked about the things that dirty code can cause.  In part 2 we followed that by giving a possible scenario of how developers get caught in a situation where they end up with dirty code.  Now in this part we will cover how to spot dirty code, and some possible situations that can be a bad “smell” and highlight potential problems.

Most experienced developers, and development “how to” books, have come to associate “smells” to help find dirty code.  Meaning that most dirty code can be found by looking for certain clues/smells, which like a bad odor can tell us something rotten is nearby.  When something smells we usually are forced to deal with the problem. (If milk smells bad we throw it out.)  The same is true of smells in our code.  Below are some common stenches we may encounter to help point out problems.

How to spot “common” dirty code

NOTE: All of the items below are not necessarily dirty code, but are merely indications that something may be wrong and require more investigation.

• Incomplete error handling – While the lack of good error handling doesn’t automatically mean the code is dirty, it is usually a good sign that the developer did not care enough to complete things.  It’s only reasonable to think this carelessness probably washed over to other areas. End-users should never see “raw” error messages, and developers should be alerted to errors.
• Memory leaks – If PHP faces a memory limitation it is usually a good sign there is bad code lurking under the hood.  We kick off an application and it is churning along, then BAM the browser goes all white.  There is no indication of a problem, except we get no results when something was expected.  Error reporting was turned on (in development), but returned nothing.  This is typical of hitting a memory limit.  In most cases this means memory was being used frivolously and not returned…poor coding. (Do not confuse this with the need to build large files or handle large chunks of data, though these can also be handled in a different manner in many cases.)
• Race conditions – Though this is rare, it is always a pain when it happens.  There are many ways this can be caused.  A simple explanation is the application execute, and expect an answer to be returned.  However, the script continues along trying to use the return prior to it being ready.  Perhaps the script is creating a file on the file-system, and tries to access the file before the file-system has finished creating it.  The script failed, and when we check the file appeared to be there.  So what happened?  Or maybe we do a few AJAX calls back-to-back and our script is not sure which answer came first since AJAX doesn’t always return the results in the same order they were called.
• Inconsistent naming conventions – Whether it’s a class, a function, or a variable, we should ensure our application is consistent in naming convention.  If we use StudlyCaps for the class name, do it everywhere.  If we are using camelCase for functions, do it consistently.  The same can be said for variableNames, that should use the same convention throughout the entire application to ensure those who follow behind us will be able to read our code.  This will also help in certain situations where we may have named a function and a variable by a similar name.  The convention will help us figure out what it actually is.  Also we should ensure that our names are descriptive and meaningful, so we can pretty much tell what is happening simply by looking at the name.  Doesn’t the function name ‘getFinanceCharge()’ make more sense than ‘charge()’?
• Inconsistent coding standard – Coding standards can encompass many areas, and there are a few different standards available (PEAR, Zend, PSR-2, etc.) for those who are not currently following one. (I will talk more about this in later parts.)  The important thing is that we have a coding standard in place, and that our team is also using it on the same projects.  There is nothing worse than starting to work on a new project and discovering that 3 different developers were working on it and they all used their own flavor of coding standard.  We spend most of our time reading code versus writing code.  A coding standard makes reading that much easier when it is consistent.  For instance, putting the opening curly braces for a function on a new line throughout an entire class does make it easier to scroll through and pick out the functions starting point, if done consistently.
• Un-initialized variables – By allowing our application to run without initialized variables we are opening ourselves up to problems.  In a loop an unset variable will retain the previous value it had from a previous iteration, causing our application to act in an inaccurate manner. This could also cause security issues where the application freely uses a variable that may have been set wrong early on, then did not initialize it again for later use.
• Code lacks clear purpose – If we look at our code and say, “Huh?”, it is usually a good sign that this “smell” is strong.  Code within an application should be clear on what it is doing, rather than like a large puzzle to be solved.  Often this is caused by poor planning, and “flying by the seat of our pants”, as we build the application.
• Large classes – Often if a class is very large it is usually because we have stuffed too many things into it.  Perhaps we have combined two or more different types of things into it and we should have actually created other objects out of them.  If a class is very long, and we find ourselves sifting through method names to figure out the one we need, we should start planning to break it up into more objects.
• Functions do too much – (more than one thing) A function should be “single minded” and do only one thing.  For me this is a difficult one I often find myself fighting internally with, and often need to return to a function and refactor to break out new functions.  But that’s OK.  We should often refactor to simplify our code.  This one goes hand in hand with unit testing (covered later), which should only test one thing.  In order to make functions testable, and single minded, they should inherently be short.  How short?  We should be able to look at a function and immediately see that it does pretty much what we expected.  Nothing fancy, or hard to follow.  Functions should be short, to the point, and easy to understand at a glance.  If a function is 100, 50 or even 30 lines long, how can we possibly tell what it is doing at a glance?
• Long parameter list – Referring back to the previous item, if a function/method is truly doing only one thing how many parameters do we really need?  Long parameter lists are usually caused by trying to keep our application DRY (Don’t Repeat Yourself).  We are working on a new part of our application and realize that we can reuse a function we created earlier, but it will require another bit of info to perform this new task.  So we add another parameter to the list and alter the function to multi-task.  Before we know it our list of parameters has grown to be 4, 5, maybe even 6. (I won’t go larger than that, because nobody should.)  I would challenge that if a function’s parameter list is longer than 2 it is doing more than one thing and should be broken down into smaller functions.  Agreed?
• Globals used – I will only say this once…Globals are dangerous, and should not be used.  In a situation where we feel a Global must be used, we need to find another way…period!  There are huge security risks, inconsistencies to be accounted for, not to mention it takes longer to code by using them.  Remember, where do we spend most of our coding time?  Yes, we spend most of our time reading code.  If we need to track down a Global, it is hard to truly comprehend the amount of time we will spend tracking down where the Global may have been set.  Imagine someone taking over an application from another developer who used Globals!  Ouch!
• Too many comments – Yeah, yeah, everyone says that commenting code is good.  So why do I feel it is a “smell”?  I feel it can be a bad smell if our code is so complex that we need to explain it.  If our functions/methods are only doing one thing, they tend to be small.  And if we add well named variables and functions to a small amount of code doesn’t that mean the code can be “self documenting”?  Instead of adding a comment, doesn’t it make more sense to simplify the code to be drop-dead simple and self documenting?
• Notices, Warnings, Fatal Errors – When I take over a project the first thing I do is turn on full error reporting and try to use the application.  This is the best way to see how “responsible” the previous developer was, and will usually give a fast indication on what size of mess I got myself into.  Developers should ALWAYS code with error reporting turn ON for their development environments.  If I see a bunch of notices and errors I know there is no way the previous developer was doing this, and that means there are probably errors that were never fixed.
• Switch statements – A switch statement is not really a bad coding practice, but it could be a missed opportunity to use polymorphism.  I have seen many applications in the past where the developer used switch statements in far too many places, and this made the application far less dynamic.  If polymorphism had been used instead and broken down into functions it would have made the application far more flexible.  A switch statement is also a sure sign we will need to return to the application at some point and edit the code when the customer requests that another criteria be added to the application.  Properly done that can be alleviated.
• Temporary variables – We have all done it, and will continue to do it.  Developers will use a temporary variable to carry a value for later use by the application.  It is unavoidable in some places, but it can also be over-used and can lead to memory leaks if not handled properly.  Temporary variable usage should be limited, and only used when absolutely necessary.
• No unit tests – Lack of unit tests are a sure sign that a developer was in a hurry.  It is also a sure sign that every line of code was not necessarily analyzed to ensure it functioned as expected.  It is also a good “smell” to highlight other potential issues, such as long functions, or functions that do too much, or large classes.  Unit testing, done properly, tests only one thing and ensures that we pay closer attention to our classes and functions in order to make unit testing work best.  If there are no tests it means we can get away with more, and be lazy.

While these are not the only “smells” that may be encountered, they are the most common indicators that ugly and spoiled things lurk inside.  Like a spoiled package of meat, you don’t need to open the package to know something is very wrong.  We should always analyze our code to look for these and other smells, then fix them quickly.  Remember, one bad apple will ruin a bunch if left unattended.  Don’t let these bad apples infect the rest of the code.  Fix them, take them out before they multiply, leave the code better than when you arrived.

As I have said many times, we read code more than we write code.  By eliminating smells we ensure that our reading, or other developers reading, of the code goes faster and enables creation of new code to be faster.  Not to mention how this affects our reputation.  If you write dirty code please believe that other developers WILL talk about you, and it can determine what jobs you get hired for in the future.  So please, write clean code and clean up old code.

Lately I have been talking about clean application development, and how developers can do a better job of it.  Due to the strong focus on this I decided to write some content from my latest talks into a series of blog posts.  Enabling everyone to reap the benefits of the subject matter, and allow attendees of my talks to refresh the content covered at one of the events I spoke at.

In Part 1 of this series I discussed the causes and effects of dirty code, and how disastrous it can be for us and/or our employer.  I think it’s easy to see how the terrible effects caused by writing dirty code is not desirable.  Most of us try to avoid wasting time, introducing bugs, increasing technical debt, causing our companies to lose money, and looking for a new job because our employer went out of business.  So if we don’t like these things, why do we write dirty code in the first place?  It is our own fault after all, but it’s not something we consciously do…most of the time.  Let’s take a look at a sample scenario, and see how we sometimes get ourselves in this type of situation:

New Job and a Simple Request

We start a new job, of perhaps we are approached by our supervisor with a request.  We know how it works.  The boss mentions how wonderful it would be if the application was able to do some sort of functionality, and asks if it’s possible.  Of course in our haste to please and impress we say, “Of course”, and head off to our lair to perform our magic.  We sit down behind the keyboard and already have an excellent idea of how to build the new functionality our boss was asking for.  What do we do first?

The Preparation

Do we write unit tests?  No.  Do we document the requirements?  No.  Perhaps we at least write down some sort of decision making flow chart?  No.  So we at least have an idea of standards we will use and follow?  No.  Well, maybe we download a framework, or figure out what functions we already have rather than recreating the wheel?  No say.

Execution

What actually happens is pretty mystical.  Like a maestro ready to conduct an elegant symphony we go back to our desk, fire up our favorite IDE or editor capable of helping us create the best code imaginable by man.  These tools have built in auto complete, connectors to version control, able to link to ticket and bug tracking systems, debuggers, project file management, structure tree display, code inspectors, refactor modules, and even direct connections to hosting and command line tools.  We can now create true masterpieces of intellectual property.

But we don’t have any time for all of those bells and whistles today.  We are excited and in a hurry to prove that our boss made the right decision by hiring us.  So instead of using these awesome tools at our disposal we code the entire thing in very short order, and then spend a few minutes to do some functional testing and ensure it doesn’t blow up on us while we demo it.

Presentation

Barely able to contain ourselves we rush into our bosses office to announce we have completed the functionality he requested.  Our excitement is quickly contagious and our boss looks on wide-eyed as we demo our accomplishment.  He is a little surprised we were able to finish it so quickly, and thanks us for our hard work.

Then, faster than we can think of what we will have for lunch, our boss immediately thinks of some sort of enhancement to the item we just completed.  He quickly outlines how it could work and what it could bring the company.  In the excitement of the moment, and our newly found feelings of accomplishment, we tell our boss it’s a small task and we should be able to get it done pretty fast.

We head back to our desk feeling the afterglow of the moment, feeling like we saved the world as well as earned our keep at this new employer.  Once again we have a task to accomplish.

Second Iteration

True to form we perform exactly as well on this second task assigned to us.  In our haste to please we ignore best practices, testing, and standards as we quickly complete the new request.  Upon completion, the meeting and presentation go pretty much like the first, and ends with yet another task.

More of the Same

This cycle continues over and over again, and we continue to perform admirably.  Our boss seems to be a wealth of knowledge and ideas, and we continue to turn these ideas into application at an astounding rate.  However, with each iteration there are more bugs, more overlap between one functionality and the next, and more “gotcha” moments as we try to demo the newly created functionality.  We are starting to struggle with the code base a bit as our technical debt has been steadily increasing little by little.

Longer Time frames

Of course we are smart, and realize very fast that those little “gotcha” moments as we demo to our boss are taking a toll on his trust of our ability.  We quickly realize we need to test a little better before presenting the functionality.  This requires some time to complete so we start to pad our time estimates a bit to compensate.  But with each task this time frame grows longer and longer, and soon these time estimates become a week, a month, two months, a quarter, then six months.

Unstable

By now our code has become so unstable we fear it, and are tripping over quick decisions made months ago.  There are no unit tests, no standard functional tests, no documented regression tests.  Our code is just layer upon layer of classes and functions that are so tightly coupled we constantly trip over them.  A change in one place causes things to break in 4 other places.  We have not even sat down and set a coding standard, let alone done any documentation of the application.

It’s at this point that every time someone makes a request our first answer is “6 months”.  However, we know in our mind that there is no way we can get it done in that time frame.  But marketing needed some sort of answer and there is no way they would settle for a number larger than 6 months.

Danger

We’ve dug a hole of technical debt over time by not using best practices, and we are in a danger area.  Our once pleased boss is questioning every choice and estimate we make.  Perhaps he is forgiving a little because he realizes we have worked so hard up to now, and we have earned some “professional credit” to this point.  We realize that action needs to happen…and happen fast.

Time to Pay

As with all debt, whether it is financial or technical, we must eventually pay it off somehow.  With financial debt we either pay it off by making payment arrangements, or we go bankrupt.  Technical debt is similar.  With technical debt we can either refactor bit by painful bit (making payments), or we can do a full rewrite of the application (go bankrupt).  Of course we could also leave the company and therefore leave the mess for someone else to clean up, but lets assume we are responsible developers and feel obligated to do the right thing.

Summary

I am sure most of us have played a part in the story above, and can nod our heads in understanding.  Hopefully most of us have learned from the experience and no longer do it. (Yeah, right.)  Those who have not had the luxury of making these mistakes should take heed of the story and learn from these common mistakes.  The story above IS NOT how to do things.

IMPORTANT: Our employers hire us to be professionals.  By following the sequence above we set the standard ourselves, in a bad way.  Please do things the right way, and be the professional you were hired to be.

Throughout this series I will continue to outline ways to avoid making these mistakes, and how we can accomplish “Clean Development”.  I hope you found this breakdown helpful, and learned from it.

Lately I have been talking about clean application development, and how developers can do a better job of it.  Due to the strong focus on this I decided to write some content from my latest talks into a series of blog posts.  Enabling everyone to reap the benefits of the subject matter, and allow attendees of my talks to refresh the content covered at one of the events I spoke at.

Whether we’re experienced developers or newcomers, we’ve all seen code that could/should have been done better.  Many times it’s even code we ourselves wrote and revisited later for one reason or another.  I, for one, have seen my share of code written by a “past me” and wondered what on earth I was thinking when I wrote that.  Of course there has also been times I was hired to fix another developers code, and it can be scary too.

Side effects of dirty code

• Time waster – The more dirty code we have, the longer it takes us to code.  Have you ever noticed that most of our time coding is spent reading code in other parts of our application?  This means that if we spend extra time sifting through dirty code, it takes us longer to actually write new code.
• Breeds more dirty code – Also, we tend to care less about our code if we know there is already dirty code in the application.  This causes us to write more dirty code, because who will notice in any way?
• Causes bugs – It’s a fact that dirty code causes bugs. (See a future section “How to spot dirty code” for more clarity.)  When we lose track of what our application is doing, and have trouble spotting problems, it simply leads to more problems.
• Excessive debugging – I often ask my audience if they are good at debugging, and usually end up with a strong showing of hands from developers who feel they are good at debugging.  But if they wrote clean code doesn’t it make sense that they would need less debugging experience, and therefore would NOT be good at it?
• Procrastination – We all do it.  We dread working with dirty code so much that we avoid it.  We make excuses to tell our customers, and we find other “more important” things that need to be done first.  I have even witnessed developers actually hiding from customers and taking on other projects to avoid a really bad codebase.
• Technical debt – This is the most dangerous effect of dirty code. Think of this as buying things on credit.  As you buy more and more the credit line grows and grows.  At some point a choice needs to be made.  Either you need to pay it off, or you go bankrupt.  With applications this means you either fix the dirty code, or go through the added expense of a rewrite.
• Financial loss – If your application has even a little bit of technical debt it causes development to slow down more and more over time.  If development slows down it can lead to your competition developing new features and applications faster than you can.  This is especially true if your application becomes stagnant and others continue to build.  A customer base can be very fickle and will leave surprisingly fast.
• Company killer – In today’s lightning fast market place it is not hard to see how the above events can quickly kill a company.  Remember when MySpace was big?  I am sure we can all think of others.

Causes of dirty code (the perfect storm)

• Too easy – Although it is easier in the long run to write clean code, we have all fallen into temptation to write dirty code to get something done quickly.  It is very easy to be drawn in.
• Short deadlines – Customers are often a developers worst enemy.  They are demanding, and salespeople have been known to over-promise on new functionality and short time-lines to meet that demand.  This places a development staff under tremendous pressure to meet those promises, and it is usually the code that suffers.
• Laziness – Yes, unfortunately there are times when we all get lazy. (Some more than others.)  I won’t dwell here.
• Lack of “how-to” – A brief look at code we’ve written in the past is a great way to see how far we have advanced.  As a consultant I often receive requests from customers to enhance applications I have built in the past, and I get plenty of opportunities to marvel at past coding methods I used when I didn’t know any better.  No matter how far I come, or how much I learn, this still holds true on a regular basis.
• Coupling – Many will recognize the term “coupling” and realize we are talking about OOP.  This is a method of helping use stay DRY (don’t repeat yourself) and making code reusable.  So, why is it bad?  That question is far too large to cover in this post, so I will make a note to cover it more later, but tight coupling is bad and loose coupling is good.  Feel free to search on your own to see what I mean.
• Impatient boss – It never fails, even if we still have plenty of time left on our project deadlines we still hear the dreaded “Is it done yet?” from business. It’s their job to ask, so don’t let it burn into you.  The faster they get it, the faster they can sell it.  But it leads to dirty code as developers strive to please.
• Bored of same ol’ app – Most large applications take 6 months or longer to build, and this can lead to some long periods of working on the same module or functionality.  Eventually developers can tend to get bored, and will try to get things finished quickly for an opportunity to work on something new and exciting.
• Intend to return for clean-up later – While in a rush to meet deadlines or to move on to more exciting tasks it is common for developers to complete things in a dirty manner with the intention of returning in the future to clean up and refactor.  Usually this never happens due to new projects and more deadlines, causing the old mess to be forgotten.

As you can see from this first post in the series, dirty code is dangerously easy to create and can carry disastrous outcomes.  I hope this post helps some to spot these pitfalls a bit easier, and make it easier to avoid them.  Please return for future installments as I attempt to highlight more areas to help us all perform clean development, and write better applications.

This animated video from RSA features Dan Pink, a well known speech writer for Al Gore and Robert Reich, has spoken at TED (YouTube), and wrote a book called “Drive: The Surprising Truth About What Motivates Us”, does an awesome job of breaking down what motivates people doing complex tasks.  It is short and easy to “get” presentation with very awesome animation. (I wish I could draw like that.)

I think some may be surprised by the message.

On May 21st, 2012 I set out on a journey to my once annual PHP related conference. I have limited myself to a single conference each year and generally work the expenses and time into my employment contract. Most companies are willing to sponsor employees going to a conference, as long as it will benefit them in some way and as long as you get it approved from the beginning of your employment. (Otherwise they “perceive” it as an expense and not an investment to gain an employee.)

I arrived early in the morning rather than later in the day (there were no flights in the middle) because I wanted to ensure I had time to network and socialize prior to the tutorials the following day. For past conferences I always enjoyed them and learned a bunch, but never really socialized much. I was the wall flower quiet person sitting in the front latching onto every word of the speakers, but then didn’t really talk much after.  This year I wanted to make it different.

Why the difference? A couple of years ago (due to events I will cover elsewhere) I decided to help South Florida enter the PHP community and grow into a place where companies could find PHP developers, and where PHP developers would enjoy a thriving community. So I started the South Florida PHP Users Group which has grown to around 270 members. In the process I learned to gain the most from any event or training through an added social aspect and that realization washed over into how I experienced Tek12.

Tek12 was very social…more social than I remember on previous times I attended. It seemed like everywhere I looked there was a group talking, and laughing.  And each group was very approachable or outright invited bystanders to participate.  Plus the groups constantly changed, so there were no “clicks” where the same people were always together.  Everyone seemed to flow from one group to another and contribute to each conversation.  I also felt very comfortable walking right up to others and simply asking a question. (Something I think most are intimidated to do.)  So I learned a bunch, and had a great time finding answers to questions I’ve had for some time.

I loved the achievement patch idea, and feel it helped by gently forcing everyone to talk to the sponsors and each other. It wasn’t like entering a large hall full of sponsor tables where you quickly passed a table grabbing “swag” and avoiding an uncomfortable product spiel on something of no interest. The php|tek crew did a good job of bringing sponsors who are relevant to current developer needs.  Not only did I learn from some of them, but I also found some services I can really use.  And I did manage to collect EVERY patch, plus one extra from Mashery for building a quick application using one of their APIs. (It is the white patch.)

Of course the sessions at the conference were wonderful with lots of great speakers. It took me a few days for my brain to catch up and actually digest the contents and topics I saw. I am still trying to work through some of them. The people who decided which talks get through the screening process did a great job of ensuring we had a good list of topics, and kept them relevant to current trends.

I also took advantage of the Engine Yard Jaunt sponsored by Engine Yard on Friday night after the conference.  It was a great way to see some sites in the city, and spend more time with old and new friends in the PHP community.  There was great pizza at Giordano’s, a tour of Skydeck Chicago, and then some night life events. (My wife and son were arriving at the airport to spend the weekend with me in Chicago, so I didn’t continue on to the club portion of the trip, but I am sure everyone had a great time.)

Of course no trip would be complete without a short jaunt with the family on a beautiful sunny day.  So on Saturday and Sunday we headed out and saw a lot more of the city, which will be posted on my more “family” oriented outlets.

The recent upgrade to Ubuntu 12.04 Precise Pangolin left me somewhat hanging when it comes to creating launchers on the desktop, and also in the Unity Launcher (also called quicklaunch in some places) for Zend Studio and PHPStorm. In Gnome prior to Unity in Ubuntu it was easy to right click the desktop and select Create Launcher to create icons on the desktop to launch applications or scripts, but in 12.04 that options is gone. So here is how I solved some of the issues.

I will cover adding Eclipse to the launcher, adding Zend Studio to the launcher, and PHPStorm to the launcher.

Method 1 (easiest)

For Netbeans and Eclipse based editors like Zend Studio or Aptana it is not too bad. I created a {name}.desktop files for each one and put it in the /home/{username}/.local/share/applications/ directory. Here is how I created a zendstudio.desktop file:

Note: If you want this option to be available for all users you can alternatively create the file in the /usr/share/applications/ directory, but that requires superuser permissions.

[Desktop Entry]
Version=1.0
Name=Zend Studio
Comment=PHP IDE for PHP development
Type=Application
Categories=Development;IDE;
Exec=/home/{username}/Zend/ZendStudio/ZendStudio
Terminal=false
StartupNotify=true
Icon=/home/{username}/Zend/ZendStudio/icon.xpm
Name[en_US]=Zend Studio

After creating the file above I rebooted. Following the reboot I was able to click the Unity Dash Home button, type “Zend” in the search field, then drag and drop the Zend Studio icon to the launcher where I wanted it to be. Now the application stays in the Unity Launcher.

For PHPStorm see method 3 below.

Method 2

Another method I found was to install the ‘gnome-panel’ package. (Actually it was already installed on my system for some reason.)

sudo apt-get install --no-install-recommends gnome-panel

With the gnome-panel I was now able to create a launcher on the desktop using the command below.

gnome-desktop-item-edit ~/Desktop/ --create-new

In the create launcher dialog I filled it out as follows:
Type: Application
Name: PhpStorm
Command: /bin/bash /home/username/PhpStorm/PhpStorm-117.257/bin/phpstorm.sh

NOTE: You could use /bin/sh or whatever shell you use. I use bash so that is why I put /bin/bash.

To create a shortcut in the Unity Launcher I double clicked the new desktop launcher I created above. (NOTE: If you start PHPStorm by executing the phpstorm.sh you do not get any options at all when right clicking the icon in the Unity Launcher.) Then when PHPStorm was running I was then able to right click on the icon in the Unity Launcher and selected “Lock to Launcher”. Voila! Now I have phpstorm on the Unity Launcher.

Method 3

This option is built right into PHPStorm. The wonderful people at JetBrains created a handy item in Tools to automatically create a menu item for you. Simply click on Tools->Create Desktop entry…and now you can Lock to Launcher the next time you run it. Start the JetBrains PhpStorm IDE from the Unity Dash you can then right click on the icon that shows up in the Unity Launcher and select “Lock to Launcher”. The icon now stays there, even after a reboot/logout.

Update:

Method 4

See comment to this post below by Shinybird on using Ubuntu Tweak. (Not sure if it works, but it sounds good.)

Enjoy!!!