10 Best Practices to Follow while writing Code Comments

Here are some of the things I try to follow while writing code:

10 tips on writing code comments

1) Focus on readability of code; assume that you don't have comments to explain the code. Give your method, variables and class meaningful name.

2) Don't write what code is doing, this should be left for the code to explain and can be easily done by giving class, variable and method meaningful name. For example:

//calculates square root of given number 

//using Newton-Raphson method

public void abc(int a){

       r = a / 2;

       while ( abs( r - (a/r) ) > t ) {

       r = 0.5 * ( r + (a/r) );

       }

       System.out.println( "r = " + r );

}

Above code is calculating square root using Newton-Raphson method and instead of writing comment you can just rename your method and variable as follows:

public void squareRoot(int num){

       root = num/ 2;

       while ( abs(root - (num/ root) ) > t ) {

       r = 0.5 * (root + (num/ root));

       }

       System.out.println( " root = " + root );

}

3) Always write why you are writing this piece of code, why you are writing this piece of code because this information is not visible until you write them in comments and this is critical to identify any bug or behavior with changing business environment. 

4) If you are writing core libraries which will be used by different project and with different teams. Follow javadoc comment style and document all assumption and precondition for using your API. Joshua Bloch has also mentioned about writing Java-doc comment in his classic Effective Java, which is worth knowing.

5) Include JIRA Number and description on comment, especially if you are modifying an existing piece of code as part of maintenance. This I found extremely useful while comparing different version of code in CVS or SVN. This gives you clear idea why that particular code has been added and whether issue is because of that piece of code or not.


6) Always try to finish your comment in as few words as possible, one liner comment is best until its explaining "Why" part and can't be replaced by code itself. No body likes or has enough time to read longer comment.

7) Don't write story in comment as your name, employee id, your department etc because those information can be obtained from CVS commit data in case someone wants to know who has make this change.

8) Always put comment while committing code in source control repository and especially why you are adding this piece of code if possible include JIRA or QC Number so that any one can refer JIRA for complete details.

9) If you want upcoming developer to follow certain standards or inform about certain things then include them in the beginning of your class as comment. E.g. suppose if you are writing serializable class in java then its good to put a serializable alert stating that any new fields addition in this class must implement serializable interface in java or make it transient etc.


10) Last but not the least give your code to fellow developer to understand as part of code review and ask him how much he understands it.

That’s all from me on code commenting, please share the standard, best practices or your experience with writing comments on code. I believe these are the areas which a junior developer or even we can improve and it’s only possible from learning which each mother's experience.

10 Object Oriented Design Principles Java Programmer should know

Object Oriented Design Principles are core of OOPS programming, but I have seen most of Java programmer chasing design patterns like Singleton pattern , Decorator pattern or Observer pattern , and not putting enough attention on learning Object oriented analysis and design. It's important to learn basics of Object oriented programming like Abstraction, Encapsulation, Polymorphism and Inheritance, but same time, it's equally important to know these design principles, to create clean and modular design. I have regularly seen Java programmers and developers of various experience level, who either doesn't heard about these OOPS and SOLID design principle, or simply doesn't know what benefits a particular design principle offers, or how to use these design principle in coding.

Bottom line is, always strive for highly cohesive and loosely couple solution, code or design. Looking open source code from Apache and Sun are good examples of learning Java and OOPS design principles. They show us,  how design principles should be used in coding and Java programs. Java Development Kit follows several design principle like Factory Pattern in BorderFactory class,  Singleton pattern in Runtime class, Decorator pattern on various java.io classes. By the way if you really interested more on Java coding practices,  read Effective Java by Joshua Bloch , a gem by the guy who wrote Java API. My another personal favorite on object oriented design pattern is,  Head First Design Pattern by Kathy Sierra and others and Head First Object Oriented Analysis and Design . These books helps a lot to write better code, taking full advantage of various Object oriented and SOLID design principles.

Though best way of learning any design principle or pattern is real world example and understanding the consequences of violating that design principle, subject of this article is Introducing Object oriented design principles for Java Programmers, who are either not exposed to it or in learning phase. I personally think each of these OOPS and SOLID design principle need an article to explain them clearly, and I will definitely try to do that here, but for now just get yourself ready for quick bike ride on design principle town :)

DRY (Don't repeat yourself)

Our first object oriented design principle is DRY, as name suggest DRY (don't repeat yourself) means don't write duplicate code, instead use Abstraction to abstract common things in one place. If you have block of code in more than two place consider making it a separate method, or if you use a hard-coded value more than one time make them public final constant. Benefit of this Object oriented design principle is in maintenance. It's important  not to abuse it, duplication is not for code, but for functionality . It means, if you used common code to validate OrderID and SSN it doesn’t mean they are same or they will remain same in future. By using common code for two different functionality or thing you closely couple them forever and when your OrderID changes its format , your SSN validation code will break. So beware of such coupling and just don’t combine anything which uses similar code but are not related.

Encapsulate What Changes

Only one thing is constant in software field and that is "Change", So encapsulate the code you expect or suspect to be changed in future. Benefit of this OOPS Design principle is that Its easy to test and maintain proper encapsulated code. If you are coding in Java then follow principle of making variable and methods private by default and increasing access step by step e.g. from private to protected and not public. Several of design pattern in Javauses Encapsulation, Factory design pattern is one example of Encapsulation which encapsulate object creation code and provides flexibility to introduce new product later with no impact on existing code.

Open Closed Design Principle

Classes, methods or functions should be Open for extension (new functionality) and Closed for modification. This is another beautiful SOLID design principle, which prevents some-one from changing already tried and tested code. Ideally if you are adding new functionality only than your code should be tested and that's the goal of Open Closed Design principle. By the way, Open Closed principle is "O" from SOLID acronym.

Single Responsibility Principle (SRP)

Single Responsibility Principle is another SOLID design principle, and represent  "S" on SOLID acronym. As per SRP, there should not be more than one reason for a class to change, or a class should always handle single functionality. If you put more than one functionality in one Class in Java  it introduce coupling between two functionality and even if you change one functionality there is chance you broke coupled functionality,  which require another round of testing to avoid any surprise on production environment.

Dependency Injection or Inversion principle

Don't ask for dependency it will be provided to you by framework. This has been very well implemented in Spring framework, beauty of this design principle is that any class which is injected by DI framework is easy to test with mock object and easier to maintain because object creation code is centralized in framework and client code is not littered with that.There are multiple ways to  implemented Dependency injection like using  byte code instrumentation which some AOP (Aspect Oriented programming) framework like AspectJ does or by using proxies just like used in Spring. See this example of IOC and DI design pattern to learn more about this SOLID design principle. It represent "D" on SOLID acronym.

Favor Composition over Inheritance

Always favor composition over inheritance ,if possible. Some of you may argue this, but I found that Composition is lot more flexible than Inheritance. Composition allows to change behavior of a class at runtime by setting property during runtime and by using Interfaces to compose a class we use polymorphism which provides flexibility of to replace with better implementation any time. Even Effective Java advise to favor composition over inheritance.

Liskov Substitution Principle (LSP)

According to Liskov Substitution Principle, Subtypes must be substitutable for super type i.e. methods or functions which uses super class type must be able to work with object of sub class without any issue". LSP is closely related to Single responsibility principle and Interface Segregation Principle. If a class has more functionality than subclass might not support some of the functionality ,and does violated LSP. In order to follow LSP SOLID design principle, derived class or sub class must enhance functionality, but not reduce them. LSP represent  "L" on SOLID acronym.

Interface Segregation principle (ISP)

Interface Segregation Principle stats that, a client should not implement an interface, if it doesn't use that. This happens mostly when one interface contains more than one functionality, and client only need one functionality and not other.Interface design is tricky job because once you release your interface you can not change it without breaking all implementation. Another benefit of this design principle in Java is, interface has disadvantage to implement all method before any class can use it so having single functionality means less method to implement.

Programming for Interface not implementation

Always program for interface and not for implementation this will lead to flexible code which can work with any new implementation of interface. So use interface type on variables, return types of method or argument type of methods in Java. This has been advised by many Java programmer including in Effective Java and head first design pattern book.

Delegation principle

Don't do all stuff  by yourself,  delegate it to respective class. Classical example of delegation design principle is equals() and hashCode() method in Java. In order to compare two object for equality we ask class itself to do comparison instead of Client class doing that check. Benefit of this design principle is no duplication of code and pretty easy to modify behavior.

All these object oriented design principle helps you write flexible and better code by striving high cohesion and low coupling. Theory is first step, but what is most important is to develop ability to find out when to apply these design principle. Find out, whether we are violating any design principle and compromising flexibility of code, but again as nothing is perfect in this world, don't always try to solve problem with design patterns and design principle they are mostly for large enterprise project which has longer maintenance cycle.

Java Tips and Best practices to avoid NullPointerException

These are simple techniques, which is very easy to follow, but has significant impact on code quality and robustness. In my experience, just first tip is resulted in significant improvement in code quality. As I said earlier, if you know any other Java tips or best practice, which can help to reduce null check, then you can share with us by commenting on this article.

1) Call equals() and equalsIgnoreCase() method on known String literal rather unknown object

Always call equals() method on known String which is not null. Since equals() method is symmetric, calling a.equals(b) is same as calling b.equals(a), and that’s why many programmer don’t pay attention on object a and b. One side effect of this call can result in NullPointerException, if caller is null.

Object unknownObject = null;

//wrong way - may cause NullPointerException

if(unknownObject.equals("knownObject")){

   System.err.println("This may result in NullPointerException if unknownObject is null");

}

//right way - avoid NullPointerException even if unknownObject is null

if("knownObject".equals(unknownObject)){

    System.err.println("better coding avoided NullPointerException");

}

This is the most easy Java tip or best practice to avoid NullPointerException, but results in tremendous improvement, because of equals()being a common method.

2) Prefer valueOf() over toString() where both return same result

Since calling toString() on null object throws NullPointerException, if we can get same value by calling valueOf() then prefer that, as passing null to  valueOf() returns "null", specially in case of wrapper classes  like Integer, Float, Double or BigDecimal.

BigDecimal bd = getPrice();

System.out.println(String.valueOf(bd)); //doesn’t throw NPE

System.out.println(bd.toString()); //throws "Exception in thread "main" java.lang.NullPointerException"

Follow this Java tips, if you are unsure about object being null or not.

3) Using null safe methods and libraries

There are lot of open source library out there, which does the heavy lifting of checking null for you. One of the most common one is StringUtils from Apache commons. You can use StringUtils.isBlank(), isNumeric(), isWhiteSpace() and other utility methods without worrying of  NullPointerException.

//StringUtils methods are null safe, they don't throw NullPointerException

System.out.println(StringUtils.isEmpty(null));

System.out.println(StringUtils.isBlank(null));

System.out.println(StringUtils.isNumeric(null));

System.out.println(StringUtils.isAllUpperCase(null));

Output:

true

true

false

false

But before reaching to any conclusion don't forget to read the documentation of Null safe methods and classes. This is another Java best practices, which doesn't require much effort, but result in great improvements.

4) Avoid returning null from method, instead return empty collection or empty array.

This Java best practice or tips is also mentioned by Joshua Bloch in his book Effective Java which is another good source of better programming in Java. By returning empty collection or empty array you make sure that basic calls like size(), length() doesn't fail with NullPointerException. Collections class provides convenient empty List, Set and Map as Collections.EMPTY_LIST, Collections.EMPTY_SET andCollections.EMPTY_MAP which can be used accordingly. Here is code example

public List getOrders(Customer customer){

   List result = Collections.EMPTY_LIST;

   return result;

}

Similarly you can use Collections.EMPTY_SET and Collections.EMPTY_MAP instead of returning null.

5)  Use of annotation @NotNull and @Nullable

While writing method you can define contracts about nullability, by declaring whether a method is null safe or not, by using annotations like @NotNull and @Nullable. Modern days compiler, IDE or tool can read this annotation and assist you to put a missing null check, or may inform you about an unnecessary null check, which is cluttering your code. IntelliJ IDE and findbugs already supports such annotation. These annotations are also part of JSR 305, but even in the absence of any tool or IDE support, this  annotation itself work as documentation. By looking @NotNull and @Nullable, programmer can himself decide whether to check for null or not. By the way ,this is relatively new best practice for Java programmers and it will take some time to get adopted.

6)  Avoid unnecessary autoboxing and unboxing in your code

Despite of other disadvantages like creating temporary object, autoboxing are also prone to NullPointerException, if the wrapper class object is null. For example,  following code will fail with NullPointerException if person doesn't have phone number and instead return null.

Person ram = new Person("ram");

int phone = ram.getPhone();

Not just equality but < , > can also throw NullPointerException if used along autoboxing and unboxing. See this article to learn more pitfalls of autoboxing and unboxing in Java.

7) Follow Contract and define reasonable default value

One of the best way to avoid NullPointerException in Java is as simple as defining contracts and following them. Most of the NullPointerException occurs because Object is created with incomplete information or all required dependency is not provided. If you don't allow to create incomplete object and gracefully deny any such request you can prevent lots of NullPointerException down the road. Similarly if  Object is allowed to be created, than you should work with reasonable default value. for example an Employee object can not be created without id and name, but can have an optional phone number. Now if Employee doesn't have phone number than instead of returning null, return default value e.g. zero, but that choice has to be carefully taken sometime checking for null is easy rather than calling an invalid number. One same note, by defining what can be null and what can not be null, caller can make an informed decision. Choice of failing fast or accepting null is also an important design decision you need to take and adhere consistently.

8)  If you are using database for storing your domain object such as Customers, Orders etc than you should define your null-ability constraints on database itself. Since database can acquire data from multiple sources, having null-ability check in DB will ensure data integrity. Maintaining null constraints on database will also help in reducing null check in Java code. While loading objects from database you will be sure, which field can be null and which field is not null, this will minimize unnecessary != null check in code.

9) Use Null Object Pattern

This is another way of avoiding NullPointerExcpetion in Java. If a method returns an object, on which caller, perform some operations e.g. Collection.iterator() method returns Iterator, on which caller performs traversal. Suppose if a caller doesn’t have any Iterator, it can return Null object instead of null. Null object is a special object, which has different meaning in different context, for example, here an empty Iterator, calling hasNext() on which returns false, can be a null object. Similarly in case of method, which returns Container or Collection types, empty object should be used instead of returning null. I am planning to write a separate article on Null Object pattern, where I will share few more examples of NULL objects in Java.

10) Avoid chaining of methods
One of the tip, which I have learned hard way is : avoid chaining of methods, like following code

String city = getPerson(id).getAddress().getCity();

Now this method will throw NullPointerException if person is null, or address is null.Instead of chaining multiple methods, you can create a separate method say getCityFromPerson(int id), that will help you during debugging to find out which field is null.

11) Prefer primitive over Objectnstead of returning Integer, Boolean or Double return primitives like int, boolean and double. Since primitive can not be null, you are sure there would not be any NullPointerException.

That’s all guys, these are couple of easy to follow Java tips and best practices to avoid NullPointerException. You would appreciate, how useful these tips can be, without too much of effort. If you are using any other tip to avoid this exception, which is not included in this list, than please share with us via comment, and I will include them here.