Cypal Solutions

Code Review Guidelines

2019-12-04T00:05:00.000+05:30

The importance of Code Review in Software Development cannot be understated. A properly done Code Review will not only improve the quality of the code & identify potential issues at a very early stage, but also helps in shaping the Developer's skills. However, most of the time, Code Review mean, just a cursory glance at the changes and provide one or two comments. Not many do a detailed and through reviews. If you are looking for how to do a better job of reviewing the code, here are some guidelines that might help you. Before getting technical, let's discuss few non-technical stuff:

First point to understated is that Code Reviews can potentially become as a collision point between the Reviewer and the Developer. The Developers (especially during the formative years of the career) tend to be possessive about the code they write. However crappy their code is, they think that is the best code ever written. In cases like these, the Reviewer has to provide a little sugar coating in the comments. Also sitting next to the developer during the code review helps than doing a remote/disconnected code review.

Next, Code Review is NOT reviewing formatting or any static analysis manually. Each person will have a personal preference on items like Tab/spaces or brackets in the same line/next line, etc. Its best to settle it in some way (dictatorship of the senior guy mostly works, but yeah, fist fight is a solution too), and every one else to follow it. Best to integrate this in the Code Formatting preferences into your the favourite IDE, so that it formats as you type/save. Similarly you can do all the Static Code Analysis (such as potential null pointer exceptions or use of deprecated methods) via various tools and integrate the same into your IDE and build process.

Lastly, do not provide subjective review comments. It only leads to collisions. When you provide any review comment, if the comment/requested change is not obvious, provide a solid reasoning on the change is required. This helps a long way in the relationship between Reviewer and Developer, and also helps the Developer to understand the things he is not aware of.

Now lets see the goal of Code Reviews.

Make sure the change does addresses the functional requirement
If possible, identify any potential issues (off-by one errors, potential performance issue etc)
Is readable and maintainable

The following guidelines should be followed and verified in the Code Review:

Naming:

"A rose by any other name would smell as sweet". Well, lets give it to Shakespeare, that is true. The same logic cannot be applied to naming classes/methods/variables in programming. Say a method that deletes an entity from the database, is better named as Entity.delete(). Any other name like Entity.hide() or Entity.remove() is not the same correct and/or effective as delete().

One real life example. Years ago, I came across a method named Tree.seachForNode(name). It was implemented as
do a traversal of the nodes in the tree and if a node with the name is found, return the same
if not found, then create a node with that name; update the tree to have the node; insert the node into database and return the node

Imagine the confusion of the callers of that method. No one would have expected that a database insert will be result of a 'search' method. That is not the case, if the method was named as createIfNotExists().

So intention-revealing-names are a very important to understand and maintain the code base.

Falls in line with the architecture:

Software Architecture is about the design choices. What framework to use; what are the individual modules; how they interact with themselves; what are the libraries to use; what are the cross-cutting concerns & how to implemented.

Single Responsibility:

Every method and every class should do only one thing, and do it well. During a review, we should verify this really happens. In practical cases, where the single responsibility is not possible, we should ensure that the method is at least broken into smaller methods, each with one responsibility. In the above example, createIfNotExists() has two responsibilities (1) Search for a node, (2) Create a node. It would better if we can break the functionality into two different methods Tree.search() & Tree.create(), and the Tree.createIfNotExists() is simply a wrapper that calls both the methods.

Abstraction:

Each layer/class/method should have a proper abstraction.

In a layered architecture, each layer should effectively hide the complexities of the underlying layer, and provide an abstraction for the layers above. For example, a Data Access Layer will effectively handle the complexities of the Data Store (foreign keys, transactions, etc) and provide a logical model to work on. The Service Layer would take up the logical model and expose the functionalities. The UI/API layer will use these services and provide the UI or API. Now each layer has an abstraction. The Business layer should not work on the foreign keys or handling the HTTP Request/Response.

Likewise, if a class called BinaryTree is trying to parse a configuration file to read some configuration, that is also a leaky abstraction. Parsing and setting up the configuration and environment variables is best done by another class, while BinaryTree's abstraction should handle only the operations of a implementing a binary tree.

Provide correct level of Abstraction:

In Object Oriented Design, an abstraction provides you an easier way to interact with, hiding all its internals. Do not over expose more than what should be known to the clients. Examples:

Should that method/variable be really public? Or may be protected will do?
In some cases, a property should only be changeable within the class, while the clients should have read only access to the property. In that case, having a public getter method is required, but why a public setter method?
Does the getChildren() method returns List? What if the client modifies the list? Does the Tree class automatically adapts? May be we should be returning an Enumerable, so that the client can iterate and access the children, but can't modify the collection?

Provide right level of abstractions, so that there won't be any unexpected behaviours.

Method contract:

Every method will have a contract. The contract consists of Pre-Condition, Execution/Behaviour and a Post-Condition. For example, lets consider insert(TreeNode) method, that inserts a new record into a database. The potential Pre-Conditions are (1) TreeNode should not be null and (2) the name field should not be null. The Execution/Behaviour is inserting the row into database and Post-Condition is that a record in the database should exist with the given values.

Pre-Conditions must be validation before beginning of the Execution. Also the assumption is that the onus of satisfying the Pre-Conditions is on the callers of this method. Any failure in Pre-Condition, the method should result in an Exception. If everything goes right with the Execution, the method should ensure that the Post-Condition is met. If for any reason the Post-Condition cannot be met, again, should result in Exception.

A typical implementation for the insert method could be:

void insert(TreeNode node){

//Pre-Condition 1
if(node == null)
throw new IllegalArgumentException("Parameter 'node' cannot be null");

//Pre-Condition 2
if(node.getName() == null)
throw new IllegalArgumentException("'Name' of the node cannot be null");

//Execution
try(get the Database Connection){
// insert into record into the database
}catch(DuplicatePrimaryKeyException e){
throw new InvalidDataException("A node with the name '"+node.getName()+"' already exists");
}
}

If you have noticed, while we validate the Pre-Conditions, valiation of the Post-Condition (whether the record exists in the database with the given values) is not done in here. This is typically verified in the Unit Tests for this method.

Choosing the right Data Type:

Choosing the right type for the given data is essential for reducing the bugs. Many times, I've come across strings used in place of enums. If the list of values are finite and known at compile time, why use string? Example: Gender.

More than enums, List is another widely and wrongly used type. Consider this:

List excludedExtensions = ReadFromConfig();

List is used to stored an ordered collection of values. Values can be duplicated too. In this cases, the file extentions to be excluded will be unique and the ordering is not important. They why use of List? Here Set is a better fit data type than a List.

Quick note on working with legacy codebases:

If you are working on a legacy code base, most probably it is not the cleanest code you have seen (if you want it without the sugar coating: its a total mess). The only way to clean it up is to do it bit by bit. Every commit you do should leave the code base cleaner than it was before. If that is not possible, at least ensure that it is not made even more dirtier. It takes a lot of patience and time to slowly fix it.

Mircosoft's new Spartan browser rocks

2015-04-17T09:58:00.001+05:30

Back in 1998, afraid of Microsoft becoming a Monopoly, the DoJ filed a suit against Microsoft. They argued that "Consumers and computer manufacturers should have the right to choose the software they want installed on their personal computers." We know how it ended. Computer manufacturers ended up pre-installing crapware, adware and spyware into Windows, making it a worse experience for the end users. But the main theme of the suit was about the browser. Microsoft ignored its browser ever since and IE became the most hated browsers by the developers.

Now times are changing. Microsoft is killing its IE brand and moving towards a new browser. The new browser, named Spartan, rocks. On a scale from 0 to 10, O'Brien says, “Let’s say Firefox is a 5, Chrome is a 6 ... Safari and Spartan would both probably be around 8 ½.". That is something amazing. Spartan seems to be a good deal for both Web Developers and End users.

Debugging IE from Chrome

2015-04-03T19:08:00.005+05:30

No, this is not an April fool post. You can really debug a web page loaded in IE from Chrome!

Chrome is slowly transitioning from a lover to wife. It used to be a sleek & fast. Now its just a memory hog and it reduces the battery of the laptop too. But Chrome's Dev Tools is simply awesome and becoming better every day. From Mobile Emulation to CSS profiling, its a tool that I can't ignore. On the other hand, IE has become the sleek & fast browser. I mostly spend my time in IE for my non-development work. Now with the new IE Diagnostic Adapter from Microsoft, you can debug an web page rendered in IE using Chrome's Dev Tools.

How this works?

Chrome has the Remote Debugging Protocol, via which it can support debugging. Now the adapter plugins into IE and provides the implementation of the protocol. For now only debugging is supported, but I hope all the other features will be supported soon. Here is the list of supported Chrome Debug APIs.

How to debug IE from Chrome?

Download the Diagnostic Adapter from here.
Open a webpage in IE
Run the Adapter
Open Chrome and point it to http://localhost:9222/.

Now you can use Chrome to debug the IE page. I hope Microsoft implements the complete set of Debug APIs soon.

Microsoft's new foldable Bluetooth keyboard

2015-03-17T15:20:00.000+05:30

Microsoft is known as a Software company, but some of its hardware is very nice to use. One of the early hardware I used was a Microsoft Mouse, and it was the best mouse at that time. Microsoft still sells mouse and keyboards, and what it revealed yesterday was something far different. Its a foldable Bluetooth keyboard, that works with multiple devices (include Andriod and iOS).

As I said here, "5 years back, if someone said that Microsoft created a cross platform device or Google created a website that works only in a single browser, I would have laughed. But today both happened. Microsoft released Band and Google has Inbox that works only in Chrome."

Now Microsoft has another cross platform device and its appealing. I wish it brings the Surface Type-Cover to iPad and Android tablets!

Rolling out Tech Preview version of Cypal Lite

2008-07-07T09:24:00.000+05:30

We are ready with the Tech Preview version of Cypal Lite. Although you can't do much with this version, this should give you a fair idea of what can be done and how the end product would look like. If you are interested in trying this out, send us a mail or leave a comment in this blog entry. For those who don't want to install Cypal Lite in their Weblogic domains, we have a small screencast also.

Cypal Studio for GWT crosses 1,00,000 downloads !

2008-07-01T21:57:00.000+05:30

The very first version of this product had nothing more than 2 wizards. It was called Googlipse and was hosted at Google Creator pages ! That version is still available and below are the screenshots of the wizards:

With that humble beginning, it has now grown into Cypal Studio for GWT. There were similar efforts to create an Eclipse plugin for GWT, but they never saw the light of the day. Since Cypal Studio is Apache Licenced, there were efforts forking this product, but I'm not sure how successful it was. People use Cypal Studio with commercial Eclipse offerings and even there is a nice tutorial on IBM Developerworks.

Today when I was adding all the download counts of Cypal Studio & Googlipse, it went well above the 1 Lakh downloads mark. In few weeks, I should be releasing 1.0 version and I'm also working with Google guys to add this tool to the Tools and Libraries page. Once both these happens, I'm sure that the download count will go up at a higher speed (currently its clocking at 250 downloads/day). Soon we will be touching the one millionth download :-)

Announcing Eclipse Utils, a new tool from Cypal

2008-06-30T23:24:00.001+05:30

We are proud to annouce a new tool called Cypal Eclipse Utils. This will be a collection of utilties that will be helpful for an Eclipse Plug-in developer. This will be a free & open source tool (Apache Licensed). This is hosted at Google Project Hosting and click here for the home page. Right now we have released the initial version with just one tool - a PDE Extension Wizard that helps the default Common Navigator. We will be adding more utilities to this and make more releases. Stay tuned for further annoucements on this. [Update] This has been added to Eclipse code base itself. So you will be seeing this wizard in 3.5 M1 onwards in your Eclipse. However for people on 3.3/3.4, can use our plugin to get the same functionality

Wizard Framework in Cypal Lite

2008-06-30T07:44:00.005+05:30

Wizards are not new in a web application. Even the old console that ships with the Weblogic server has a wizard framework. Check this screenshot:

But there are few issues with this, such as the placement of buttons or the irregular size of the wizard that keeps on changing with every page. And as with other pages, the wizard will fetch every page from the server, which means network delays and load on server. In middle of the wizard navigation, if you click any link outside the wizard by accident, all your changes are gone! Frustrating?

Welcome to the wizard framework in Cypal Lite. Once again, its carefully designed not to have any pitfalls as in the old console. A typical Wizard would look like:

The entire wizard will be in fixed size and navigation buttons will be in the same location - no matter which page of the wizard you are looking at. The page title and description would differ for each page and will hint you about what that page does.

The wizard would behave like a modal dialog. You can move it to any place in the window, but you can't click on anywhere outside it. Onlyway to dispose the dialog would be to either click Submit or Cancel.

To avoid round trips to the server, we have validations made in the browser itself:

As you see in the above image, the fields would have descriptions like "Enter JNDI name" and if there is an error, then its will be clearly indicated with different CSS style. The errors are "live errors" - meaning to say, the field value is validated as you type. A nice example of this would be:

If at least one of the fields in a page has error, the page is said to be incomplete. The Next button will not be enabled if the page is incomplete. And the wizard's Submit button will not be enabled if at

least one of the pages is incomplete:

To sum up, a wizard framework is nothing new, but we have taken a lot of care about the user experience in using this wizard. That has been done without hurting the performance. So that means the server would be contacted only if you press Submit and until then its free to do

other important tasks :-)

We have sorted out many issues and only a few issues needs to be nailed down. The Tech Preview should be available within 2 weeks.

Revealing Cypal Lite screen shots ...

2008-06-25T00:43:00.006+05:30

For those who are curious to know about Cypal Lite, the light weight Ajax console, here are some screen shots. When you login, this is the screen you would land at:

One of the emails we have got asked, "Ajax application? So what is the fanciest widget you used?" The answer, as you might have seen in the screen shot above, is none. Just because its an Ajax application, doesn't mean that we should be adding fancy widgets and exoctic animations. While its all possible, we selected the other route - a simple, neat and elegant UI. Simplicity is given atmost importance, so is usability. So the home page would contain the quick links, that you would be using frequently. You would see shortcut buttons placed at appropriate locations. The screen real estate is properly designed for maximum use, at the same time not cluttering the UI. For instance, the navigation bar is shown by default and the Activity log is hidden by default. If you require, you can always see/hide both. The below screen shots depict this.

BTW, if its not clear, Activity Log is the place where we log you edits, undos, redo, etc, so that you can refer what you have done so far.

If you click an item in the navigation bar, a corresponding tab will be created in the UI.

The advantage is that, if you want to move from the Servers tab to the Jdbc tab, its just a single click away. There is neither the overhead of fetching the details from the server nor the overhead of disposing the current UI elements and creating new UI elements. It just appears as soon as the mouse button is released when you click. It can't get any faster than this, that too in an web app

Except for the Home tab, all the other tabs are closeable. So what is the content of a tab? The content is fairly dependent on what tab it is. But most of the tabs have one single table, like this:

All the tables are sortable by *every* single column in them, and the user is free to select which columns to view and which to hide. You will have the Pagination controls at the bottom of the page, and in the text box you see there, you can say how many records you want to see in an single page. All the details of the table are configurable. Remember, all these operations (sorting, pagination, column selection) are done within the browser. This means no server process/network overhead.

You can also see action buttons in the bottom of the table along with the navigation. These should serve as the context sensitive quick links.

Now what is in the Action Bar?

As you can see from the first screen shot above, all the controls are in disabled state. When you start performing operations like deploying an application, deleting a data source, changing the port of the server, etc, each of those operations will be wrapped into a command and executed on a command stack. The buttons will reflect the status of the command stack and enable themselves accordingly. Can you localte the annoying "Lock & Edit" button? No? Its because we don't have it. Our console is little intelligent that it locks automatically when you perform the first edit operation. It will be released whenever you press Save/Cancel. Simple? Now you must be wondering why the old console didn't provide it

We will soon come up with the screenshots of the Wizard framework. Till then, post your comments/suggestions here or mail to cypal-lite@googlegroups.com

Cypal Lite, a light weight console for Weblogic

2008-06-22T00:04:00.003+05:30

If you have ever worked with Weblogic, you probably know the pain of the product - its webconsole. Every release, the server gets faster and faster, but the console goes otherwise. Newly added features simply pull down the performance. Add it to the not-so-nicely designed UI, you end up clicking so many times and starting at the screen for the page to be loaded.

Well not anymore. We are working on a light weight console, which would allow you to do things much faster. We call it as Cypal Lite and more information is available here: www.cypal.in/lite We will be pushing updates in this blog, so stay tuned.

Hello World !

2008-05-18T23:28:00.000+05:30

Welcome to our blog. This is the place where we discuss about our upcoming products, design, thoughts and random stuff. Stay tuned.