Recent blog entries for idcmp

Navigation 2.0: The Missing Features

I recently found myself driving a car in an unfamiliar city relying heavily on Google Navigation on my phone to get me from point A to point B (and back to point A again). From this two week experience I found some things in the Navigation experience I'd really love to have. Maybe other Navigation apps have this and I've just been googleblind.

Not Looking At The Phone

Most of the time I'm driving, I'm relying on Navigation to tell me what's going on. You're probably the same. Some simple options would make me a lot more comfortable. These also apply to when I'm on a motorbike and my phone is locked away in a pocket.
  1. Don't tell me compass directions: If I'm in a new city, in a new area telling me "Head East" is useless. Especially at night where I can't use the Sun to figure out which way East is.
  2. Give me a hint which lane I should eventually be in, "Travel three kilometers, eventually turning left."
  3. If I'm driving for thirty minutes on a highway, periodically remind me that you haven't crashed or suddenly run out of battery power. Even a little beep every 10 minutes (or % of a leg) would be nice. Maybe even tell me what % of battery is left.
  4. Along those lines, since Navigation knows how fast I'm going and how far I have to go, telling me "Continue for about 15 minutes." is more handy than "continue for 23 kilometers".
  5. On navigation start, tell me something useful; even "Route calculated" or "Estimated twenty minutes of travel time."
  6. If I'll have less than 10% battery life by the calculated arrival time, tell me this up front and give me the option to just read the list without actual navigation.
  7. It may annoy you, but I like to know when Navigation has changed its mind about where we're going. Telling me that a route has been recalculated is re-assuring.

Tell Me Less

There are some things where being quieter makes more sense:
  1. Cut me some slack in a parking lot. Unless you're going to tell me exactly how to get out of the parking lot, keep quiet until I'm close to an exit. Calculate some routes of the closest few exits and get ready to tell me "Turn left here." or "Turn right here.". Telling me to "Head North to 11th Ave South West going to 23rd Street East going East." is just distracting while I'm trying to navigate the maze of grocery carts and SUVs.
  2. Some cities have Main St. North, West, East, South or North East / North West / etc.  If I'm on "Main St North West" turning onto "1st Street North West", don't say "Northwest" both times.  In fact, unless I'm close to a boundary where it's important to know which cardinal direction of the street I'm on, simply saying "Turn left onto First Street." is fine.

Nicer Touches

And there are a few nice things I bet wouldn't be too hard.
  1. Traffic Lights. I'm sure most cities have a database of which intersections have traffic lights. Telling me "At the lights, turn left onto Third street." trumps "In six hundred and fifty meters turn left onto Third street.".
  2. Let me mark certain areas as "well known" areas and silence turn by turn directions if my destination is in that area unless I ask for them to be re-enabled.
  3. All major highways in Canada have numbered exits. They're numbered based on kilometer distance. If I'm at exit 35, and I'm going to exit 25, I know there's ten kilometers to go. When I get on a highway, let me know the exit number I'm going to be exiting on.
  4. If I'm going to a destination that has a Google Place (or whatever they're called now), and it seems that they'll be closed or closing within an hour of the calculated arrival, give me an option to call the place.
  5. Let me tell Navigation how comfortable I am with a given city or area. If I don't know it very well, give me notifications earlier and take me on possibly longer but easier to navigate routes.


Syndicated 2012-05-24 23:28:00 (Updated 2012-05-24 23:30:54) from Idcmp

New Plugin: licensing-maven-plugin

Ever wanted to know what licenses your dependencies (and their dependencies) are using? Maybe you work for a company that wants to sell their source code so you're wanting to avoid the GPL (and AGPL)? I've got the plugin for you!

I mentioned a while back that the build process at my day job had been declared bankrupt. Well, it's doing much better now; what used to be a multi-day process where you were never quite sure if it was working 100% now takes less than an hour (including data population). We're quite happy about that part.

Along the way we started looking at some of the other bits that fit more into release management; one of them was a "licensing report". This report listed most of our dependencies and which open source license they were in. Instead of hacking at the old scripts, we decided to let Maven take over and handle providing licensing and dependency information.

So with a rough idea of what we wanted to do, I put together the Licensing Maven Plugin. It has a few handy features:

  1. Transitively aggregate licensing information of dependencies of child modules in multi-module reactors (or in English, it works the way you would expect it to on multi-module builds).
  2. Coalesce license names (so "Apache License, Version 2.0", "Apache 2.0" and "ASLv2.0" can all be reported as "The Apache Software License, Version 2.0").
  3. Fail builds if a dependency is only available under a disliked license.
  4. Exempt artifacts under disliked licenses from failing the build.
  5. Manually declare licenses for dependencies that fail to provide their own.


It's hosted on central, so give it a whirl:

mvn org.linuxstuff.maven:licensing-maven-plugin:1.5:aggregate

You'll see a truckload of warnings go by, and when it stops, you'll have a target/aggregated-third-party-licensing.xml file (yes, I know it's not nicely formatted yet).

If you'd like some more details, checkout the licensing-maven-plugin README.


Syndicated 2012-01-09 07:54:00 (Updated 2012-01-09 08:41:16) from Idcmp

New Plugin: licensing-maven-plugin

Ever wanted to know what licenses your dependencies (and their dependencies) are using? Maybe you work for a company that wants to sell their source code so you're wanting to avoid the GPL (and AGPL)? I've got the plugin for you!

I mentioned a while back that the build process at my day job had been declared bankrupt. Well, it's doing much better now; what used to be a multi-day process where you were never quite sure if it was working 100% now takes less than an hour (including data population). We're quite happy about that part.

Along the way we started looking at some of the other bits that fit more into release management; one of them was a "licensing report". This report listed most of our dependencies and which open source license they were in. Instead of hacking at the old scripts, we decided to let Maven take over and handle providing licensing and dependency information.

So with a rough idea of what we wanted to do, I put together the Licensing Maven Plugin. It has a few handy features:

  1. Transitively aggregate licensing information of dependencies of child modules in multi-module reactors (or in English, it works the way you would expect it to on multi-module builds).
  2. Coalesce license names (so "Apache License, Version 2.0", "Apache 2.0" and "ASLv2.0" can all be reported as "The Apache Software License, Version 2.0").
  3. Fail builds if a dependency is only available under a disliked license.
  4. Exempt artifacts under disliked licenses from failing the build.
  5. Manually declare licenses for dependencies that fail to provide their own.


It's hosted on central, so give it a whirl:

## NOTE: If you're reading this early Saturday morning (07-Jan-2012), central may not have synced 1.5 yet.
mvn org.linuxstuff.maven:licensing-maven-plugin:1.5:aggregate


You'll see a truckload of warnings go by, and when it stops, you'll have a target/aggregated-third-party-licensing.xml file (yes, I know it's not nicely formatted yet).

If you'd like some more details, checkout the licensing-maven-plugin README.


Syndicated 2012-01-08 07:54:00 (Updated 2012-01-08 07:56:46) from Idcmp

14 Dec 2011 (updated 17 Dec 2011 at 07:28 UTC) »

Hello Developers, look at your code.

Hello developers, look at your code, now back to me, now back at your code, now back to me. Sadly, your code isn't me, but if it stopped collecting tech debt and you started making time for technical quality it could smell like me. Page down, back up. Where are you? You're at an interface with the code that your code could smell like. What's in your hand, back at me. I have it, it's an oyster with two different implementations to that thing you have an API for. Look again, the implementation is now secure and scalable. Anything is possible when your code has no smells. I'm on a horse.


Syndicated 2011-12-14 09:03:00 (Updated 2011-12-17 07:26:00) from Idcmp

A Patentable Idea

A quick post that if someone were to come up with a "USB Charger Condom" that I could plug into those free charging stations (or into my phone) which acted like an application layer proxy for my phone and prevented the charging station for giving anything more than power and not access anything on my phone that I'd gladly use one, and I'd make everyone I know use one too.



Syndicated 2011-11-01 15:37:00 (Updated 2011-11-01 15:37:05) from Idcmp

Real Reasons Developers Leave Jobs

While I'm still working on improving my commenting skills, I've also started trying to ponder how to write software in company with high developer turnover.

You see, I've always said that software reflects the team that writes it.  If you have a team of people who are seriously experienced at writing stored procedures and OSGi, you can expect that the software they write will use that.  On the flip side, a team who knows JavaScript and CSS, asked to write the same software will write something completely different. So, given an environment that has higher turnover, how does someone design a system that embraces and survives?

While I was researching about turnover, I found a survey on why developers left their current positions (or rather, why they would leave their current position).


The survey is a bit older, but the list is pretty fascinating:
  1. Higher Salary
  2. More Experience
  3. More Interesting Work
  4. Need for a Change
  5. More Challenge
  6. Greater Chance of Promotion
  7. Better Location
  8. Present Company Getting too Large
  9. More Control over own Work
  10. Keep Up With Technical Knowledge
  11. Run Own Company
  12. More Flexible Working Arrangements
  13. Greater Structure in Work
  14. Go to More Successful Company
  15. Difficulties with Immediate Boss
  16. Friendlier Company
  17. Opportunity for Equity Stake
  18. Go to Less Commercial Company
  19. Go to More Commercial Company


Syndicated 2011-09-27 04:50:00 (Updated 2011-09-27 04:50:31) from Idcmp

Write Better Comments by Tomorrow Morning

I've spent some time recently trying to improve my code comments.  Most of us just write comments without much thought and carry on with the task at hand, however after a couple of weeks of iterative improvement I have some really simple tips that will make you write better comments tomorrow.

Tip 1: Delete Bad Comments

If you're working on a large code base, you'll invariably find some comment that's questionable, but sometimes you'll find comments that are even worse, and those comments simply need to go.  To me, the two kinds of comments that fit in this category are:

  1. Machine generated comments: These tend to be blatant and useless.  "The getFoo method gets Foo." or "The isNotEnabled method returns the value of notEnabled.".  If you're using Eclipse, the shortcut Ctrl-D can be used to delete a line and these comments are ripe for the killing.
  2. Lies: Over time code is refactored, shaped, copy-pasted, "fixed", outsourced, insourced, sold, bought until it eventually winds up in front of you.  During all this ebb and flow, some comments don't keep up with the code.  If the method signature you're looking at is "public List obtainShipments(Locale locale, Country country);" and the comment is "This method will return true if the system can ship to the given country." then you know it's wrong.   If this is not code you're currently cleaning up, then delete it.  
Wait, this sounds harsh.  You should spend the time to rewrite it as a proper comment, right?  Wrong, and here's why.

If you've been a developer for a while, you know the feeling of being "in the zone".  That time where the entire system you're working on is in your head and you can think of side-effects and how everything works.  You're one with the matrix. If you're not working on the methods with the generated comments and lies, then you're not going to add any value trying to write comments and it's going to pull you out of the zone; so don't.

Also, the comments that you see there will leave you (and others) with the feeling that comments are there to help you.  You've probably scanned a class before and thought "Uh-oh, there's almost no comments here, this could be tricky."  With the above two types of comments in that class it gives you a false sense of security.  You've got source control.  Bad comments are worse than no comments, delete them and move on.

Tip 2:  Explain the WTF's

Sometimes the code you're working on has something weird and counter-intuitive about it.  Things that you totally understand, but others may not.  Usually they're the result of bugs or missing features elsewhere in the system.  When you're writing code that works around a bug, go find the issue # in that project's issue tracker and add the full URL in a comment.  Also explain what you would rather the code do if the bug weren't there.  If there isn't an existing bug then file one.  You may discover you misunderstood some functionality or that it's fixed in a newer version.  

If you can't upgrade the library you depend on, mention that the bug is fixed in a newer version in your comment. Also, if you use a dependency management system like Maven or Ivy, add a comment near the dependency "Version 2.1.2 will fix BUG-7509 and then we can remove the workaround in SuperFancyImpl". This tiny investment of time will help the next developer who looks at the code.

Tip 3:  Describe Relationships

More than the other two tips, this tip takes your comments to the next level.

A developer will stumble across your code, following data flow.  They'll want to know why your code is here and how it interacts with other code, so tell them!

Lets imagine a restaurant simulator.   As a developer you find the "Table" class.  Comments like "A table in a restaurant." or "An implementation of a Table." are good Ctrl-D candidates.  Instead, here's something a little better:
"Tables represent a location in a restaurant where customers are served food.  Restaurant Customers attach themselves to a Table which is then served by a number of TableWorkers including the Server Employee and TableCleaner.  It is often allocated by the Reservation system, check CustomerSeater for how Customers are seated.  Constructed Tables usually come from the TableFactory and are always added to the RestaurantBuilding."
Let's take a look at the recipe this comment follows:
  1. Who Am I: If this class represents a business object or business activity, then copy and paste the description from any documentation or planning sessions you've had.  If there isn't any, then write a note to yourself about why you decided you wanted to make a new class.
  2. My Close Family: This class describes very simply how it interacts with other classes around it, either in the same package or members that would reference it.
  3. Bend Encapsulation: In the comment we mention TableCleaner as an implementation of TableWorker.  Chances are the Table class doesn't have any code reference to TableCleaner, but our comment does.  This can be an "Aha!" moment for a developer.  Eclipse is smart enough to dig around in comments when you're refactoring so it's not as dangerous as you might think.
  4. Use "usually" and "often": Should Table know that it comes from a TableFactory? No.  Should a developer know this? Absolutely.  By saying "usually", we hint to the developer that this is probably the common case, but because of the separation we can't say definitively this will be true.
The last two ingredients are what makes this comment a cut above the rest. It helps guide me up and beyond what most other comments would help me with.

What If I Have To Have Comments?

You might wondering what to do if you have a tool that enforces comments in your system and will fail your CI build if you start getting Ctrl-D happy.  It's pretty simple, disable the rules that force you to write comments.  

At my work place we have rules that all methods must have comments, and comments must end with a period for proper grammar.  Want to know what comment I've seen more times than I'd like to admit?

 /**
  * .
    * @return boolean .
    */

Yup.  The problem with enforcing comments is you're enforcing their existence, not their content and simply having a comment isn't ever going to be enough.  The code metric tools don't enforce quality, just quantity.  So ask people around you if it's more important to have lots of comments or if it's important to have better comments.  Maybe for your workplace, quantity is better...
 
That's It!

I'm still experimenting with other techniques, but so far these have had a great impact in my development. Other tips and ideas are welcome!


Syndicated 2011-09-17 04:25:00 (Updated 2011-09-17 04:25:25) from Idcmp

30 Mar 2011 (updated 8 Apr 2011 at 00:12 UTC) »

Technical Debt

Our build came up recently in a planning session at work. It's a standard big ball of mud, with hidden knowledge all over. It's frail, inconsistent and unhelpful, it's complicated to work with and almost nobody ever gets their local build past "good enough for now" to "working well".

This has been an issue for a while and it hadn't been given the proper attention to be improved. Every change had been reactionary to various needs and it had changed hands so many times that any beliefs or design philosophies it had were long lost.


One developer estimated that wrangling the build system alone accounted for 30% of their development time (that's three days of a two week iteration).

When asked how much effort was required to fix it, the answer was "You can't."

Taking Out Your Technical Loan

While I wasn't originally, I'm now a fan of the term "technical debt". It brings with it a handful of related concepts and terminology that make discussions easier. In this case, compound interest, and bankruptcy.

It all starts when you first make a big investment; probably your first release. Fixing up the last minute bugs before release, cutting corners in the name of getting to market, making "just for now" trade offs going against technical soundness. Each of these things add to your technical debt. There's nothing wrong with this, it's expected.

But then your debt starts adding up pretty quickly:
  • Changes in business needs for the system
  • Changes in company direction
  • Changes in team composition, staff sizing
  • Cutting corners on in-code documentation
  • Industry changes
  • Not keeping up with underlying frameworks
  • Not following proper language techniques
  • Quick security patches
  • Scalability needs
  • Blindly meeting code metrics
  • Over reliance on under-skilled developers
  • Not testing on up to date integration points (databases, operating systems, etc)
  • Quick and dirty bug fixes
  • Minor improvements
Any of these things can put you further into debt, and while you're in debt you'll need to pay compound interest on your technical debt. What was one day of work to fix this iteration can become two days of work a few iterations from now and a week of work next release. Leave it longer and suddenly it's a month of work two years from now.

How does this happen?

Lots of ways.

One of the beautiful things about refactoring is the way it takes into consideration the "context" that a developer has gained in immediately working with the code. Their short-term memory is filled with nuances and intents and allows them to glide smoothly through code. They can envision the refactoring and perform it optimally.

As time passes, they lose some of the context. Surrounding code begins to change, bug fixes are introduced, and other developers build on what was written instead of what was intended. More time passes and other code is refactored, team members come and go or the pattern gets copied elsewhere in your code base.

A few iterations later, there's a hierarchy of dependencies built on this code and what was once a simple refactoring has become a costly code spill cleanup effort.

Eventually the frameworks become out of date and coding styles fall out of style. Instead of wanting to clean up the code, new developers will work around it, introduce a functional duplicate, wrap it or simply make their changes as a series of hacks.

If code quality drops too low, some say morale will follow and keeping more than a handful of experienced developers will become a challenge; attracting developers eager to land their first job, negative velocity developers or those that simply don't care.

This affects your ability to pay off your debt.

Ways To Pay

Every organization has different priorities, goals and principles. As such, calculating how or where to pay for your technical debt varies wildly. Of course, the rule of thumb is "Pay off debt that is costing you the most." There are a handful of ways to do this:
  • Research and Analysis: Work to establish what business functionality should be delivered next then prototype any areas that are known hot spots or developers do not have experience with. With the gained experience determine if the code in question is deeply in debt or if it can afford the new feature.
  • Raise Rates: When asked to estimate a new feature in an area that has high technical debt, focus on estimates which include needed code revitalization. Just as it's the business duty to plan features customers want, it's a developer's responsibility manage risk ensuring it's done technically correct.
  • Foreign Exchange: Exchange the technical currency into salaries as an incentive to keep developers. Many larger, non-technical firms follow this route. It's like buying carbon credits; the debt is still there, but developers are rewarded for tolerating it.
  • Creative Accounting: Buffer estimates and deliverables with needed cleanups. Once someone knows an area of code well, perform small improvements under other ledgers.
  • Get a Second Job: One of the most dire methods is to band together and either work nights or through lunchtime to make the needed improvements.
  • Bankruptcy: Sometimes there's honestly no other choice other than to start over.
Back To The Build

Our build system had gone bankrupt. It had gained such complexity that we could no longer service the interest on the debt.

In our case, this opened the door to switching build tools, cleaning up packaging and performing much needed work on the development environment. It's exciting, as it will not only boost the productivity of each developer, but it hopes to also be something that isn't always dreaded; so developers can focus on solving their problems more effectively and not how to make sure everything builds properly.

And, if the payments are made on it on a regular basis, serve our needs well for years to come.




Syndicated 2011-03-30 04:07:00 (Updated 2011-04-07 23:08:43) from Idcmp

22 Oct 2010 (updated 22 Oct 2010 at 05:16 UTC) »

Who Owns Your Code?

At work, our marketing team is in control of deciding where development spends time on products. This is an effective way to ensure that our product meets the needs of the market we're in.

In fact, I would say we have an effective backlog of "big features" that are desired by our target market. We're only limited by the resources we have on hand to deliver these features. Therein lies the challenge; almost every feature is done on a tight timeline, and once it's in a non-laughable state, it's released and the team goes on to the next big feature. No time is really spent revisiting the overall design of the product, or just bringing its dependencies up to date.

In a previous workplace, the development team had strong say on what was worked on. This was an effective way to ensure the product was relatively nice to work on and its technology up to date. New features were strongly scrutinized and often there was a focus on picking newer technologies that made it easier to develop and service. The challenge was we'd fall behind on bolting on new business features from time to time.

In yet another workplace, our SEO team had the strongest say in what happened. Our main products were publicly accessible websites, but I feel like this was a pretty unique situation. Many technical decisions had to be discussed with the SEO team (which CMS should be chosen, which captcha system should be employed, etc..) and everything from character set encodings, performance trade offs and cache expiry times needed to have their approval. Our challenge there was that the success of some SEO practices are not easily measured, it was difficult to assign a ROI on particular decisions.

Who owns your product? How does that shape it?


Syndicated 2010-10-22 03:05:00 (Updated 2010-10-22 04:45:46) from Idcmp

Negative Velocity Developers

I've worked on a handful of projects over my career where there's been a developer that I've started to coin as "negative velocity".


Their positive impact on projects is best when they're on vacation or spinning their wheels in meetings. Everything they touch could instantly earn an @Deprecated annotation, and often when they're focused on their next tasks, the rest of the team is left to either throw out and rewrite, duplicate in parallel or at best refactor the work they've done.

Some of the best code they write is copy and pasted from other code, some of the worst is of their own design. Often the team works hard to try to minimize the impact of the developer, but they simply just don't understand what they're doing.

Agile projects make the results of this developer even more vicious as they get to choose what area of the project they will molest next. Also, many teams are "agile but" where the team follows some practices, they are not empowered to remove that developer from the team.

Often those that make employment changing decisions don't have the tools to validate such a claim. So what's one to do with a negative velocity developer? How does one capture enough information to prove to someone non-technical that their skill sets would best be used elsewhere?

Note: This is not a current situation for me.


Syndicated 2010-10-13 03:24:00 (Updated 2010-10-13 03:58:44) from Idcmp

66 older entries...

New Advogato Features

New HTML Parser: The long-awaited libxml2 based HTML parser code is live. It needs further work but already handles most markup better than the original parser.

Keep up with the latest Advogato features by reading the Advogato status blog.

If you're a C programmer with some spare time, take a look at the mod_virgule project page and help us with one of the tasks on the ToDo list!