Relocating my blog

After three years using the https://onlysoftware.wordpress.com domain and after several articles, it’s time to relocate my blog to a new domain and transform to a platform which will be more than just a blog.

From now I’ll stop posting here and I invite you to join me at the Software Garden which will host my online presence.

Bookmark this page : http://softwaregarden.io and be part of the software gardeners community

Do you want a car with wheels, brake or throttle? The Software development paradox!

Imagine that you want to buy a new car because the old-one is … really old, you got sick of it and you need a change. You go to a car dealer, you see a couple of models that you like and you ask them for some details, pricing etc. The salesman full of smile replies to you with the following question:”Do you want a car with wheels, brake or throttle?”. Note that these are XORs, You can have only one of them. How would you react? Don’t answer … it’s a rhetorical question!

Imagine now that you work for a software development company and a customer wants you to build a system for an online ticketing platform. Would you (or your sales department) ever ask him to choose one of the following : “Reliability, performance, code quality, alignment with business requirements”? Of course not! So why do we make such choices during the development life-cycle? Why do we sacrifice so many and obvious things when we write software? And please don’t tell me that we don’t have enough time or enough budget. We do have time and budget to fix all these bugs that we created because we have made such ugly choices, right?   

I don’t understand why I have to choose between doing the right things, over doing the things right. I don’t understand why I have to write performance-friendly code no matter how difficult is to understand it. I don’t understand why I have to make choices. Would you ever buy a car if you knew that there are no security tests before the car gets into production? Would you ever buy a car if you new that the interior is from such (poor-quality) materials that they’re going to break after one month or melt during a warm day?  So why do you build systems like this? Why do you allow yourself be a part of that? 

Unfortunately, everyday we make such choices or we are forced to, by these creatures called managers and It’s really disappointing that we don’t learn from our mistakes. So wake up!

Managers : Listen to your senior and experienced developers. Even prime-ministers have ministers and kings have consultants! (nobody is perfect)
Developers : Fight for your right to achieve perfection. Fight for your right to write code you’re proud of and creates less bugs (nobody is perfect)
Customers : Fight for your right to get high-quality software that meets your business requirements. It’s your money after all!

 

Photos from my JEEConf talk

In a previous post I briefly described my experience during JEEConf. Now it’s time for some pictures taken during my talk and one during the SonarQube workshop, so here they are

 

 

JEEConf at a glance

Last week I had the chance to be part of the one of the major development conferences in Eastern Europe : JEEConf. Although I stayed only a couple of days and I attended only the first day of the event I came back full of lovely memories. In this post I will try to summarize my experiences and my impression about the event.

To be honest, I was very skeptical and concerned before I got to the plane from Thessaloniki to Kiev:) . Reading online articles and watching some TV clips about what was going on in Ukraine made me wonder about what I was going to find at that place. But what a surprise : Kiev is no different with any other capital city I’ve visited. Nothing could make you believe that somewhere in this country people are fighting for territories. The city was full of people from early in the morning until late at night and not even a single moment I felt like being in a war-zone as I was initially afraid. 

Now back to the conference. Even though Ukraine is not in the best situation of the last decade, almost 700 hundred people attended JEEConf. This number is the same with last year’s which means that the event was a great success under the current political circumstances. Like I said I was there two days. The day before the official start, I held a SonarQube workshop and I think attendees learned a lot of interesting staff about continuous inspection. During the day, we had lunch at a great place near the workshop venue and I tasted some of the traditional Ukraine dishes 🙂 . The first day of the main event was indeed full of great talks. Unfortunately I only attended three of them because the rest was in Russian 😦 and I don’t understand a single word : 

1. Tooling of a Test-Driven Developer by Paweł Lipiński
I am a fan of TDD and unit testing so I was expecting to see some cool tools specialized for TDD. The presentation was great. The speaker is an expert on his field and he’s really experienced. I had the chance to learn about the AssertJ framework with some cool live-coding examples, JUnitParams, a library implemented by the speaker for making JUnit Parameterised much easier and catch exception, a nice utility for writing better assertions on expected exceptions. All these things were really interesting but … I wouldn’t use the word TDD for the presentation topic, as all of these are great tools for Unit testing but unit testing is not practiced only with TDD. No matter what I enjoyed the talk so kudos to Pawel!

2. Mobile functional testing with Arquillian Droidium by Stefan Miklosovic 
The second talk was also very promising. Functional testing for mobile devices using Arquillian? Seriously? I needed to see this! I learned a lot interesting things watching the presentation but I have to admit that I was expecting more. The speaker had some technical problems for the first 15′ so he had to run his slides a little. If I were him I would have skipped the introduction part for Arquillian and I would go straight to the meat with Droidium. The tool looks great but I’d prefer to see in details some more examples or spend some even more time describing the features and some best practices. One thing is for sure, however, I will surely try Droidium in the near future.

3. Memes and Cargo Culting in Java by Nicolas Fränkel (Switzerland)
Last but not least it was the talk of Nicolas Frankel . I think it was the best way of closing a great conference day. Nicolas has a great sense of humor while presenting without however missing the core points of his talk. The idea of his presentation was genuine and innovative, although not very technical, but like I said it was exactly what we needed as attendees for our last talk 🙂 With ‘imaginary’ examples, because none of these could never be true ( LOL ), he explained several of the paradoxes that we all have seen with our eyes in our software development career. That was definitely the best talk out of the three that I attended. 

Aside of these talks I had the chance to meet some great speakers I already knew and some new ones ( Sergey Kuksenko , Peter Ledbrook, Aleksey Shipilёv, Alexey Fyodorov , Gleb Smirnov , Yakov Fain … and of course : Nicolas Fränkel ) 

I will definitively be there for JEEConf 2015 edition and the only thing I’d suggest to the organizers: Please add some more English talks 😀 

P.S. Thanks a lot for your kind words and the feedback I got for my talk : Holding down your Technical Debt with SonarQube . 

See you next year!

Rest API best(?) practices reloaded

The last one and a half year I’m involved in 2-3 projects that expose a big set of Rest APIs for “external” use. I will come back later and explain why the word external is insides quotes. During this period we had to design, re-design and re-structure some times these APIs. This blog post expresses my personal thoughts about some best(?) practices that will help you when dealing with Rest API.

Design well, design early

Implementing Rest services is a very trivial task for many languages. This means that, no matter which underlying framework you choose, with some minimal configuration and a few lines of code you can have in less than an hour a running Rest service. While this is really convenient, especially for inexperienced people, it can lead you very quickly to a low-quality API design. So before you start writing some code, step back for a minute (or more) and think. Try to design your API. Spend enough time to understand the business domain and figure out what API clients need from your system. For instance, if your system is a database for coin collectors, decide if you want to allow clients to add new coins or just fetch existing data. What kind of queries are needed? How will you handle requests that will retrieve a large amount of data? Answering this questions quite early will help you develop a more realistic API. 

Names and Methods

There is a lot of discussion out there about resources naming and how they should be organized. Again based on my experience I suggest three, simple to follow, rules.

1. Use ONLY nouns. For instance if you want to provide a service for searching the coins database avoid naming the endpoint like this : /searchCoins or /findCoins or /getAllCoins etc. A simple /coins resource is enough so when clients send a GET request that resource they will expect to get a list of all available coins. Similarly if you want to add a new coin to the database avoid using names like : /addCoin or /saveCoin or /insertCointToDatabase . You can just use the resource you already have for fetching coins and instead of a GET request, just send a POST request or a PUT request for updating a coin.
2. What about getting a single coin. The suggested best practice is to use an endpoint providing a resource parameter so for instance if clients want to get the coin with id 20 then a GET request to /coins/20 should be enough. Let’s see another more complex case. Let’s say that that you want to allow clients to add images for each coin. A quick but dirty solution would be : /addCoinImage or /addNewImageToCoin etc. A slightly better approach would look like /coins/addImage but like I said just throw away any verbs. So we can step on the resource we provided for getting data of a specific coin and allow clients to add an image by sending a POST request to this endpoint : /coins/20/images. So far so good. But every rose has its thorn. Let’s assume that we want to allow some super-users to delete coins from the system. Based on what we discussed until now a simple DELETE call to the /coins/{id} resource would be enough. But can you imagine how problematic would be that approach if the {id} is just a sequence number of the table “COINS” ? Someone could start sending DELETE requests to that resource by increasing the id number each time causing our system to eventually lose all data. My point is that using identifiers as resource parameters is fine as long as these identifiers are impossible or too hard to be guessed. So if you identify an entity with a serial number just forget this implementation. What I suggest is, instead of passing the coin identifier as a resource parameter, send a DELETE request to the /coins resource and include in the request body (let’s say as a json document) enough parameters to uniquely identify the entity object you want to delete.
3. Use domain specific names as much as possible. If your domain has an entity of Coin Collectors then just use the word collectors instead of users or accounts when designing the API. Try to avoid too generic names that don’t mean anything or are controversial to the clients. Follow the same principles for query parameters as well. It’s also strongly advised to keep the names of query parameters as short as they get, but still meaningful. For instance if you want to query coins that was issued in a specific year a very nice choice for the query param could be : issueYear where as the following names are too large or might confuse clients : year (not clear), yearOfFirstIssue (useless extra information) 

 

Error handling and Responses

When dealing with errors and responses my experience shown that it’s much easier for clients to expect the same json response structure every time they send a request, no matter if the outcome is successful or not. For instance let’s say that you want to add a new coin sending a POST request to the resource /coins. A successful response might contain the following json document

{
     "meta":{
      "code":200
   },
   "data":{
      "coinId":"a7sad-123kk-223"
   }
}

and an error response something like this :

{
     "meta":{
      "code":60001,
      "error":"Can not add coin",
      "info":"Missing one ore more required fields"
   },
   "data":{
   }
}

Notice that for both possible outcomes (error, success), the json response document has the same basic structure. There are two basic elements:meta and data. The former contains information about the result and in case of error includes a specific error code, a message (“error”) describing what went wrong and a more detailed explanation (“cause”) of the root cause of the failure. The latter (optionally) contains any data returned from the service. For instance in the example above, when adding a new coin is successful the service returns back the unique auto-generated identifier for that coin. In case of error, typically this element should be empty. The gain of this approach is that clients always expect a standard return for all services of the same API. Moreover we can pass additional information when something is not completed successfully. Clients can use (at least) the error attribute to show it as a message to the end user and use the info attribute for logging purposes. Alternatively they can handle the responses based on the error code as long as they know the meaning of each number. Please bear in mind that these error codes are not http statuses. You should still return the correct http status upon each request (i.e. 400 , 401 etc. )

Before we discuss the subtopic of documentation I’d like to point out another important thing you need to have in mind. Assume that we don’t allow the deletion of coins coins but a client tries to send a DELETE request at the /coins/{id} resource. Normally it will get back a 405 http error from the web container. I find very useful to filter all these responses and return again the same json document. So in the case of the above error we could return  

{
     "meta":{
      "code":405,
      "error":"Method not allowed for the /coins/{id} resource",
      "info":"Method DELETE is not allowed for that resource. Available methods : GET, POST, OPTIONS"
   },
   "data":{
   }
}

Isn’t a lot better? The response contains the same information ( 405 http error status ) but additionally informs the client the available methods for that resource. 🙂

Documentation

Last but not least. Spend some time to provide a professional and developer friendly documentation and make sure that is always updated. An outdated documentation is far worse than no documentation at all. You can use one of the several open source and free tools that exist for that purpose and well-document all your APIs. Even better, provide examples of using each resource and give the expected outcomes in case of an error or a success. Don’t forget, finally to document each error code and provide adequate information so that clients know when errors occur. Several clients ignore any response messages and prefer to provide their own messages based on the error code. 

I still have a couple of more practical advice to write down, especially about API versioning and security but I think both of them can fit to a different blog post 🙂

If you liked this article don’t forget to share it and have a look at my upcoming book :“The Art of Software Gardening”

The art of software gardening

The inspiration

A couple of years ago I read for the first time this article :“You’re NOT a software engineer“ and from that point it was clear to me that I couldn’t agree more with the expressed ideas. I was always comparing software development with engineering ( building bridges, building etc. ) and it looked quite a straightforward comparison. But that was until I read that article. Every time I read it I believe more and more that systems are gardens and source code are flowers and plants. 

This article inspired me to start writing “The Art of Software Gardening“ , a book that discusses the essential skills, the proper attitude and the useful practices that modern developers should have in order to master the art of software gardening. While writing it, I decided to post to my blog some articles to allow potential readers have an idea of what’s inside and for me to get some early feedback. This article presents several examples about the analogy of comparing software engineering with gardening.  

(Partially) Explaining the analogy

So what do these two “professions” have in common? Let’s start by an essential soft-skill and some attitude examples

• Growing gardens is something that requires patience. You don’t just plant some flower seeds today and expect to see them blossom in tomorrow. This procedure takes time and while waiting to see the results you have to be there and ensure that everything is going as expected. For instance several flowers won’t grow up if they are over or under irrigated. Plant diseases, also should be controlled early or prevention actions should be taken before they are noticeable. The same applies when you write some new code. You have to be patient. It’s better to deliver a bug-free (no-disease), fully-covered by tests (protected by future diseases), and well-designed (correctly irritated) feature (flower) one or two days later than trying to deliver it today with a poor design, complex code and nothing to prove that’s working. 

• Successful gardeners are committed to their professional in the essence that they don’t perceive it as a “task”. They give flowers every day, every moment their love and affection and they are rewarded for that, when the time comes. These emotions get back to them with a feast of beautiful colors and sweet smells. Love your job as a developer and be passionate about coding. Treat source code like a small kid that needs your attention and very soon you will see the advantages and the benefits : Clean, maintainable code (colorful flowers) and systems without bug-reports (fragrant gardens). Code is not your enemy. If you find yourself struggling writing a piece of software then think for a moment if you haven’t given from the beginning the right attention. Step back for a minute and try again … 😀

• It’s very common that some times things don’t work like a charm. Some ugly plants are getting too big hiding the beaut, or you notice that several flowers are getting withered. Gardeners just uproot anything that’s blocking their design or doesn’t fit in the garden. Do the same with your code. It’s not the right time to be emotional so without any second thought throw away any code that’s not needed (withered flowers) any more or is causing too much troubles (too big / unwanted plants). 

That was only the beginning and this article just put the little finger in the honey pot. As long as my free time allows more articles will be added to my blog post. In the meanwhile you can take a look at the contents of the upcoming book “The Art of Software Gardening“ and since nothing is finalized yet feel free to comment, suggest, argue and of course declare your interest and get notified for future updates and news. To give you a clue about how content is structured, most chapters of the book apart of a detailed and explained gardener – developer parallelism will contain real-world practical examples and ideas that will make you a better professional, a real software gardener. 

To be continued… 

 

SonarQube workshop at Craft Conference

Last month, I had the chance to hold a SonarQube workshop at Craft Conference with a great success. A lot of people attended the workshop and my overall experience with the organization was awesome.

Below you can find some pictures taken during the workshop.

 

International Software Developer Conference in Greece Survey

We are all aware of the numerous software development conferences around Europe and the U.S. Some of them are specialized in a topic and some others cover a broad range of topics. Participating in such events has several benefits : new knowledge, skills, useful experiences, socializing, even new job opportunities. I’m sure that, people that attended at least one conference, can verify that.

We all know also that in Greece there aren’t many conferences. As far as I know, there’s a successful uncoference in Crete (jcrete.org) that takes place 4 years in a row. This May, for the first time Oracle will organize after some years of inactivity a Java Day Event and there’s a new uncoference ( agilecrete.org ) targeting agile practices the upcoming September.

This survey, I’m kindly asking to fill contains a few easy questions about the possibility of organizing a 2-day International Software Development Conference in Greece. The more answers we get the better conclusions and decisions will be made https://www.surveymonkey.com/s/VJ9XQNF

Thank you in advance for your time and don’t hesitate to ask or comment anything you feel it’s useful.

 

To SonarQube or not to SonarQube?

This is the first question that a team leader, s/w director, customer, developer, architect, tester or whatever role exists in a development team should ask. It’s not yet another question about using another “quality tool”. You already have plenty of them installed. This is not a simple question to see how much you care about test coverage or to find which classes have the most issues. There is no competition and no prize about that! It’s the only question that you needto answer in order to show how much you care, how much you REALLY care about the overall quality of your code. If you have never used SonarQube or even heard about it, then this is your chance to find out how this little (but great) piece of software have changed our lives (as developers) and enhance our products.

Darkness. This is how I describe our development life before SonarQube. We had no insights of our code. We ran no unit tests. We did not know whether the current design allowed us to quickly add new features or make important changes, which made us apprehensive about any refactoring attempt. Coding rules; Issues; what the heck are these? Duplicate Code? God bless copy – paste. Testability, Stability, Changeability were terms we needed to look-up in a Chinese dictionary to find out their meaning. Bugs were discovered late in the development lifecycle causing some red-alert situations and releases seemed to be some kind of middle-age dragons that our support and test department had to fight before they come out to our customers. And then some kind of a miracle happened. I can’t remember how I reached SonarQube, but right now I am quite sure that, those 10 minutes I needed to read SonarQube’s features, changed our mindset.

Without any second thought I downloaded and installed it. Full of excitement I analyzed my favorite project and after a couple of minutes I was starring at my screen in front of my first ever SonarQube dashboard.My first feeling was an extreme disappointment:”Our code sucks!”. Soon I realized the possibilities of this unknown to me tool and I was stimulated about the potentials. Immediately I showed it to my team, shortly explaining them, the different metrics and their meaning about code quality. A new era has begun. Today, SonarQube tracks all our projects. Every morning team members check the project dashboard, especially the differential views from last analysis. We have configured thresholds for the most important metrics, so whenever new code reach a threshold, build is broken. We handle these builds just like all broken builds: Fix them ASP and restore the required quality. Before we begin a refactoring task we always consult SonarQube for signs of poor design. We continuously strive to focus on code quality from the first day of the project and SonarQube is the best ally we could ever hard. I love to see my bubbles(Motion Chart) changing colors and moving towards perfection. I love to see my projects treeview getting green from red. With a single view I can figure out which components need our further attention. Just pick up the red big-ones and start cleaning up your code!

Our new product releases are much more stable. From dragons are transformed to butterflies. Trust and confidence in our team has significantly grown. We feel no fear when we add new features or modify existing ones. In other words, this is our SonarQube life! Sometimes, I wonder how our code could “breathe” some years ago. SonarQube gave us the missing oxygen. I have answered the question to myself. I have chosen light instead of darkness. it’s your turn now!

My advice to (junior) developers about their career

The last couple of months I have met several young developers that either looking for the first job or are still trying to get their bachelor degree. Many of them asked me to give them my advice on how they can make their first steps in the software development career. It’s really nice to see young people to care so much about their career. I don’t remember that the guys of my age had the same mentality. I assume it’s the economic crisis that made all these young people act so maturely, but I like it 🙂

In this post I summarize my advice to all these “young” and ambitious developers. Don’t be fooled by the word young. Even you have already 10 years of hands-on development on your back, you’re still young. At least, me, I feel this way.  

The first thing they ask me is to tell them which language or framework should they learn. I can give you a hundred of different answers but the key is not which language you already know but how quickly you can learn a new language. Do you think that Google, or eBay, or Amazon care if you’re a Java or JEE or JavaScript expert? Send your CV and have an interview with some techie guys … 🙂

IT companies should hire characters and train skills. Ok, I know that this is not always the case but sooner or later, nobody will ask you to list all the programming languages or frameworks you know. If you are a “Lucky Luke” character no-one will ever want you in the team. The age of super-hero-programmers has passed and I don’t see it will ever come back. Teamwork is one of the keys to success and you should be prepared for that. And what about skills? If you can’t learn a new tool, a new language or a new framework, you still have enough time to pick up a different career. Companies will invest on you to teach you new skills but you should be a fast learner and be able to adopt these new technical skills in your everyday work.Think for a second about the definition of “investment”. Yes, you are right. Companies are not offering this education as a gift. They expect from you to pay back this new knowledge by increasing your skills, your productivity and eventually the company’s value.

Another great idea is to be open-source friendly. Pick up an open-source tool you like, you know well, or you just find it interesting, and join the community. Try to be active, to participate in forums, and why not, contribute on the project. There’s nothing better than showing to your future employers your real work in an open-source project. Moreover, open a github account, if you haven’t done it already. Push your personal projects. Let others see that you’re passionate about software development and you’re not just consider it as a way of getting some money. And since you have your github account read others code. It’s a great way to open up your mind and learn new things for languages you’ve never seen.

Be agile! Learn how to write clean code, no matter what’s the language you’re writing code. Learn how to respect yourself and the other developers of your team. Your code reflect your personality. A messy code will probably make your colleagues think that you’re the same in your personal life. You don’t want to hear from your co-workers “WTF is this?” when they read or review your last commit. Learn design patterns and re-factoring. You can apply them to almost all famous languages and they surely make you write cleaner code.

Join local user groups and go to some conferences. It’s incredible how many things you learn when you meet people from different cultures, backgrounds and knowledge. You have nothing to lose. On the contrary I can assure you that it’s a win-win situation. Not to mention that you will increase your social circle and maybe improve the chances of getting a new job.

Finally build your brand. I may sound like a marketing-guy, but I’m not. Advertise yourself with your achievements, even if you’re the millionth guy that did it. It doesn’t matter. Let others know your interests and that you’re active in software development. LinkedIn, Twitter and other professional networks can help a lot. Start blogging and post little articles about your experience and knowledge, even if they’re for beginners. Again, it doesn’t matter!!! You’ll find yourself very soon posting more and more advanced stuff. 

And one last thing… Don’t you ever stop learn new things. You decided to become a software engineer. This is your destiny. To continuously learn new things.