Tag Archives: java

Review of Clean Code

The Clean Code is a book by Robert Cecile Martin, a pioneer of agile software craftmanship. This book was recommended to me last year on an Agile software development training by Cegeka in Belgium. I have read it and I must admit that it has had an impact on my work as a Java developer. Of course many similar books are available. But this is the first one of this kind I read.

In my company we had one hour lasting sessions, in which we read two chapters and discussed content of the book together with our practical experience we had. It was good approach and I liked it. Therefore I think I received more from the book then I would have learned alone just by normal reading from start to end.

I will do my best to do a review of the Clean Code for you. I am going to start with a little motivation, then what I learned and used after one year and then a summary of pros and contras.

“I am a good programmer, I can do my new task fast, it is normal that code is messy…”

I sometimes deal with such statements. They are true or false based on the perspective. If you were a typical startup developer, then I would say yes. There is no high demand for a good design. Time and a number of implemented prototypes is what it counts. But if we took a look for example on a complex middleware system of a large business, then I think that such statement as in the headline would be wrong. Let’s focus on these large enterprise systems. Based on my experience, some programmers are not able to foresee or are not capable of long-term thinking. Unfortunately I already spent too much time analyzing badly written code some else’s. Because it was written without thinking that another programmer would later need to work on it, to understand it. The original target was to finish the task as soon as possible (and unfortunately without seeing the consequences). Of course the latter task is expected to be finished as soon as possible too. But now it is different, now it is more difficult.

Let’s admit it. The most of the development projects are about team work. If we want to consider ourselves to be good team players, we should write our code with respect to our valuable colleagues. To make them their job as easy as possible. To keep in mind that they will once most likely read our code. They will have to understand it, change it and refactor it.

Now from the management perspective. I understand how deadlines are important. However I think it is beneficial to support developers and let them write clean code. The subsequent software support costs will be much lower.  A good manager should take care not only for the next approaching deadline, but he should always plan the project in a way, that there is a space left for improvements and clean code. In other words I think that a good manager must treat deadlines and long-term project sustainability equally to produce the best value for their company. What I mean – the first barely working solution is not the same as the working solution that is already easy to understand and easy to change.

Clean Code principles as I remember them after one year

The book contains quite a lot of chunks of the code. The reader may train his skills on those. I read this book about one year ago, so I do not remember everything exactly, but I’ll try to summarize what I remembered and applied in my projects. I am going to structure the list of the principles as I remember them and order them depending on how often I use with them.

Responsibility principle

Every class or method should have one clear responsibility. If I find a class or method that it deals with more responsiblities, then I’ll separate the responsibilties by creating a new class or a method.

Usually when the class or method is too long it is also an issue. In such long implementations we can usually identify more responsibilities and find out which responsibilities should be separated. It also means that the operations should not have side effects.

Distinctive class and method names

This rule applies more often for method names. Simply make their name as distinctive as possible. Better a long distinctive name than a shorter one, which is ambiguous or unclear. Also a long descriptive method name is better than a short name and a piece of Javadoc.

Understandable method calls

Very common problem. It is very difficult to read and understand method calls with too much parameters. I try to use one argument, two in fewer cases and three only exceptionally. It really helps. Another thing to mention is that it is better to write methods that do not need to accept arguments as null (what is this null?!), true/false (what is actually true or false?!), etc.

 Keep classes small, single purpose and unit testable

Small classes are not just about lines of code. Also the amount class fields and method needs to be reasonable.

Testability is very important. Always design with testability in mind. Write unit tests for your classes. Then you may freely refactor without fear that you’ll break something. Such fear is very common and many programmers rather stay out of trouble, e.g. they don’t dare to change the code they do not understand. I think this is bad habit and also a sign of badly written code. Another common problem is that the unit test is trying to test more than is expected from the tested class. In such a case, the test needs to be moved to the appropriate place.

Pros and contras

I took a look on the book. Of course the book contains more topics, like concurrency, error handling, etc. It contains a lot of practical examples to force you to think. I did not cover everything. Let’s summarize pros and contras.

Pros

  • A lot of useful information for your developer career. Senior developers are basically those, who are able to work independently, but I believe that knowledge of such book belongs to their knowledge as well.
  • Experience from the experts in the field.
  • Good structure.
  • Clear argumentation.
  • Practical examples.

Contras

  • Examples are sometimes too long and it’s quite difficult to focus on them.
  • Our reading group in my job agreed, that not everything can be easily applied. Some of the rule recommendations seemed unnecessarily strict to us.

Conclusion

This book is about opinions, how the good code should look like. It carries knowledge and experience of the author and his friends. You may not agree with him, but it is still definitely worth reading. At least you can confront your development style with the one offered by the author.

I liked this book. It helped me to improve my Java coding abilities. I am sure it helped our team as well. I would recommend it to every Java developer, who works in a team. As a bonus I would recommend to organize a reading group in your company as we did. It forces you to read the book regularly. The discussions afterwards with my colleagues were very beneficial.

If you have something to add or you disagree, feel free to leave a comment!

How to call DB procedure with MyBatis and Java annotations

According to MyBatis pages: “MyBatis is a first class persistence framework with support for custom SQL, stored procedures and advanced mappings. MyBatis eliminates almost all of the JDBC code and manual setting of parameters and retrieval of results. MyBatis can use simple XML or Annotations for configuration and map primitives, Map interfaces and Java POJOs (Plain Old Java Objects) to database records.”
I often face MyBatis configuration hidden in mapping .xml files. I wanted to try something different. As I learned from Spring, configuration can be also stored not only in XML files, but also in Java annotations. Spring enabled this possibility in its later versions. I found on the net that the MyBatis configuration may be stored there as well, but on the other hand I lacked enough of good tutorials. That is why I decided to write a blog post about this topic. The information, that was needed, I found on stackoverflow.com and I gathered the pieces together here.
Let’s imagine a stored procedure, which is able to change a status of a car entity. For example we want to change the status of the car to ‘sold’. So we need to define an own Java annotation, which is registered in Spring configuration file. Then we define a mapper interface. If you are already familiar with MyBatis, you should have an idea, how this looks like. But on the contrary this time we create no .xml file in resources. We just define everything in the annotation. Let’s see an example:

@MyBatisCarProceduresMapper
public interface ChangeCarStatusMapper {
    
    @Insert(value = { 
            "{ call DATABASE.PACKAGE.CHANGE_CAR_STATUS ( #{car_id, mode=IN, jdbcType=VARCHAR, javaType=String },  #{car_status, mode=IN, jdbcType=VARCHAR, javaType=String },  #{result_code, mode=OUT, jdbcType=NUMERIC, javaType=Integer},  #{error_description, mode=OUT, jdbcType=VARCHAR, javaType=String} ) }"
            })
    @Options(statementType = StatementType.CALLABLE)
    void changeCarStatus(Map<String, Object> parameters);
}

This deserves an explanation. To call a procedure successfully we need an @Insert annotation. We can see two input and two output parameters. Also we need to define type of the statement. That is all. So it’s a more compact and effective solution, but it has also some disadvantages. For procedures with large interfaces it may become confused. Also big problem is lack of friendliness of Java in case multiline String constants. Usually you have to split such long String to more lines and use always concatenation. Also the fact that you are combining more languages in one source file may be questionable from the clean code and design perspective. But I think that despite these disadvantages it can be still advantageous for small procedure interfaces.

My first release!

Yesterday I released the first version of my jBPM workflow plugin. I started research and development of this JenkinsjBPM integration at the university in November 2011. And my company let me to continue work on my project. That’s great, because this is one of the things, which keeps my job from becoming monotonous and also I have learned a lot of knowledge by working on this project.

Continuous integration helps many companies in their software development. Jenkins is one of the most widespread CI servers. It’s used for several purposes – building software, running tests, publishing results, software analysis, etc. As a quality engineer I have mostly experience only with Jenkins as a tool for running many matrix tests. Axis include operating systems, Java development kits (JDK), databases, Java content repositories (JCR) and web browsers. Many test types are included too like unit, regression, integration, performance and others. And as you continuously work on something, you tend to optimize your steps.

So back to start – I had to apply for a master project and found an interesting topic. The task was to create a Jenkins plugin, which would enable to run test plans by using business processes to improve efficiency of the quality engineering department. If you spend less time with starting, monitoring and evaluating Jenkins jobs, then you have more time for other tasks, for example improving test coverage of a product. I defended the master’s project and continued to improve it.

Now the early release of the plugin has been done. However current solution still has several limitations. It can fully run only in JBoss AS 7 container. What is meant by fully? That means running business process with persistence enabled. That’s necessary if you want to easily recover the latest state from database in case of unexpected outage. Theoretically the plugin should run without persistence on any container, but I have not verified that. And also it’s necessary to mention that the JBoss AS needs its jpa subsystem to be disabled. That can be real limitation if you host more applications than Jenkins in one application server instance.

Problems that had to be solved

I’ll try to summarize problems I faced with the implementation of the plugin.

Jboss AS 7 Hibernate was not able to find persistence.xml of my plugin

This happened because of complexity of combination of Jenkins and JBoss classloading. Jenkins uses several classloaders and one of them is dedicated for plugins. So the Jenkins .war is deployed in the application server, but deploys .hpi file by its own mechanism. This was solved by changing context classloader of the plugin thread to that dedicated classloader.

JBoss AS 7 had a tendency to supply its own Hibernate

After many failures I have decided to supply hibernate .jars directly with the plugin and od not depend on the ones provided by JBoss AS. But running two Hibernate frameworks together could not work. I have tried many things how to disable classloading of Hibernate into Jenkins or into my plugin using the jboss-deployment-structure.xml. This file should exclude or include specific classpath elements specific for your application. Unfortunately without success. So I had to disable jpa subsystem in standalone.xml configuration file. This way correct Hibernate is loaded and is able to find the persistence.xml file.

Transaction issues

I had also issues with transactions, but honestly I don’t remember them exactly. The solution was to implement own way for looking up a transaction manager.

Future of the plugin

Current implementation of the plugin has its drawbacks, these include:

  • need for setup an additional Jenkins job for launching the business process build step with with test plan
  • only JBoss AS 7 with disabled jpa subsystem is usable for persistence

The best approach to solve this can jBPM remote handler implementation. This handler implements a work item handler in jBPM for JenkinsJob service task. It’s the same service task  as in jBPM workflow plugin, or at least with the same interface. You can supply it in the same way with the job name to launch, optionally with parameters in case of parameterized build and receive an object as a result. This is great since you can use both integration approaches and your business processes will remain the same. Only handler implementation changes.

Remote handler as the name suggest will start and evaluate Jenkins jobs remotely. Business process instance will run in jBPM console (simple process server) or a user application, which uses jBPM engine inside. jBPM console can also handle human tasks, for example for decision of the QA engineer like what to do if basic tests failed etc. The main benefit will be decreased complexity of the integration implementation and also there will be no limitations on application server for Jenkins.

Conclusion

I have learned a lot of technical stuff on this project. I have understood many concepts. But most importantly I have learned that it’s not a good idea to integrate two complex technologies directly on the application level. At least in Java you’ll end up with many classloading problems. If you can oppose this, please leave me a comment, thanks.