Coding conventions - class and method structure in Java

It is very important to follow a consistent coding structure in classes and methods. Following a consistent structure will increase the readability of your programs. Very often companies have their own set of guidelines for namng and coding conventions. If the company you work for has it's own standards then you should follow those. All team members should ideally adhere to the same standards to make the code more readable. If everyone follows their own individual standards, the developers who have to maintain the code will find it very difficult to understand the code, as they navigate from one class to another. It is like driving on a street where everyone drives on the left till you reach a stop light, after which everyone is driving on the right.  Most people will manage, but it will be difficult and slow.

I have shown a simple class below with all the elements that a class usually comprises of. Click on the play button to hear an explanation of the class structure.

01 public class ClassStructure { 02   //we first declare constants 03   public static final int MAX_VALUE = 10; 04  05   //then public attributes 06   public String someString; 07   public int someValue; 08  09   //then private attributes 10   private String name; 11   private long salary; 12  13   //then constructors 14   public ClassStructure(String name) { 15     this.name = name; 16   } 17  18   //then public methods 19   public void parseClass() { 20     parseElement(); 21   } 22  23   protected void updateSalary() { 24     //do something 25   } 26  27   //then private methods 28   private void parseElement() { 29     //do something 30   } 31 }

Java2html

Notes: This text was originally posted on my earlier blog at http://www.adaptivelearningonline.net
Here are the comments from the original post

-----
COMMENT:
AUTHOR: B.M.Rao
EMAIL:
URL:
DATE: 01/16/2007 05:09:54 AM
Hi Parag,
that was a pretty good introduction.Only thing i had to add is that i think we should be declaring unmodifiable attributes as final.For example in the sample attribute "name" could be declared as final as it is not getting updated after being initialized in the constructor.

COMMENT:
AUTHOR: Parag
DATE: 01/17/2007 05:34:29 AM
Hey B.M.
That is a good suggestion.

COMMENT:
AUTHOR: Supriya Shinde
EMAIL:
URL:
DATE: 02/02/2007 02:16:49 PM
Hi Parag Sir,
Being a beginner readability forms an imporatant part for understanding the codes. But, i would also like to know if for IT audits there are some particular or standard conventions that are used for the auditing purpose. That is, on what basis are the codes exactly audited. Are these conventions important for auditing purpose or only for readability convinience?

COMMENT:
AUTHOR: Mitesh Desai, SCIT
EMAIL:
URL:
DATE: 02/02/2007 02:20:06 PM
Hello sir,

I would like to add upon your coding convention that we can also have conventions for public and private variables and objects. like we can have following variable names:

if x is an object of a class: - o_x
if x is a private variable: - p_x
if x is a public variable: - m_x

we can have similar conventions for more efficient and readable codes.

COMMENT:
AUTHOR: Parag
DATE: 02/02/2007 05:32:34 PM
Supriya, these conventions are used purely for readability. Audits are done on various factors, and code conventions may be one of them... however the primary reason is to make the program more readable for those who will maintain it.

--
Regards
Parag

COMMENT:
AUTHOR: Parag
DATE: 02/02/2007 05:37:00 PM
Mitesh, using special variable names to add extra meaning to the variable should be avoided. In fact many people prefer not to do that because if you change the variable from let's say protected to public, you must change the name also. This can break a lot of programs that depend on that name. We should avoid adding metadata to variable names.

--
Regards
Parag