[Guide] How to make understandable and easy to use code

[Intrepid1989]

Introduction:

 

Such a subject is the key of everything. It covers all the basics of what has to be done in order to have a well organized smoothly packed software. Easy to use and to understand for some people means that you have to keep everything at the lowest level as far as coding goes while thats not true at all. What you need to know to make such a codepiece is to follow always the conventions of yourself based on:

 

• Naming Conventions
  
• Code Documentation
  

 

Naming Conventions:

 

What is naming convention:

 

Naming conventions are rules that every developer can and should follow. These rules make your codestyle your very own. Naming conventions involve the conceptional creation of packake/class/object/method/variable names.

 

Why you should use a naming convention:

 

When you make a piece of code what you do is implement your own style in it. That either you want it or not going to be impossible to understand or use for another person IF you dont use a convention that others can follow and depend on when they use your code. Better convention you use better your code will get because what you do is increasing the readability of it. Readability is the single most important thing because better the readability is less time you need to find out what the code does and how it works which means much faster development in every way.

 

In order to understand that here's an example:

 

You want to switch a pack because your previously used pack isnt good enough for your needs. You choose a pack and than you end up with days/weeks spent only with learning how the pack works. Why it would have been easier if there would be a naming concept which could let you know how the code works instead of making you find it out yourself.

 

How to implement naming conventions:

 

To make changes regarding to that what you should think about is what your code does. For example if you want to code an event you use the name of the event and names related to it if you want to code a feature you use the name of the feature and names related to it, doesnt sound hard does it?

After you apply logical and foolproof names for all your packages/classes/objects/methods/variables you are on the road to have a well developed software for yourself and if there's any than for your community.

 

The standard java naming convention:

 

The following rules are general java conventions.

 

• Packages:
  Names should be in lowercase. With small projects that only have a few packages it's okay to just give them simple (but meaningful!) names:
   
  package pokeranalyzer
  package mycalculator
   
  In software companies and large projects where the packages might be imported into other classes, the names will normally be subdivided.
  Typically this will start with the company domain before being split into layers or features:
   
  package com.mycompany.utilities
  package org.bobscompany.application.userinterface
   
   
  
• Classes:
  Names should be in CamelCase. Try to use nouns because a class is normally representing something in the real world:
   
  class Customer
  class Account
   
   
  
• Interfaces:
  Names should be in CamelCase. They tend to have a name that describes an operation that a class can do:
   
  interface Comparable
  interface Enumerable
   
  Note that some programmers like to distinguish interfaces by beginning the name with an "I":
   
  interface IComparable
  interface IEnumerable
   
   
  
• Methods:
  Names should be in mixed case. Use verbs to describe what the method does:
   
  void calculateTax()
  string getSurname()
   
   
  
• Variables:
  Names should be in mixed case. The names should represent what the value of the variable represents:
   
  string firstName
  int orderNumber
   
  Only use very short names when the variables are short lived, such as in for loops:
   
  for (int i=0; i<20;i++)
  {
      //i only lives in here
  }
   
   
  
• Constants:
  Names should be upper case:
   
  static final int CONSTANT_EXAMPLE
   
   
  

 

Code Documentation:

 

What is Code Documentation:

 

Comments are explanatory notes for the humans reading a program. With good name choices, comments can be minimal in a program. The only required comments are block comments just before the class declaration (after any import statements) and just before each method declaration.

 

Other than block comments, one other time to add comments is when your code is unusual or obscure. When something is important and not obvious, it merits a comment.

 

Block Comments:

 

Javadoc is a program that examines the declarations and documentation comments of your code to produce a set of HTML pages. These pages describe your code to other programmers. For an example of the documentation produced, see the Java API documentation.

 

Some of the Javadoc is derived from specially-formatted block comments, which you create as follows:

• 
  Indent the first line to align with the code below the comment.
   
  
• 
  Start the comment with the begin-comment symbol (/**) followed by a return.
   
  
• 
  Start subsequent lines with an asterisk *. Indent the asterisks with an additional space so the asterisks line up. Separate the asterisk from the descriptive text or tag that follows it.
   
  
• 
  Add a description of the purpose of the class or method.
   
  
• 
  Insert a blank comment line between the description and the list of tags, as shown.
   
  
• 
  Insert additional blank lines to create various tags.
   
  
• 
  The last line begins with the end-comment symbol (*/) indented so the asterisks line up and followed by a return. Note that the end-comment symbol contains only a single asterisk.
   
  /**
  * The main method for the HelloWorld program.
  *
  * @param args Not used
  */
   
   
  
• 
  For more information on the tags, see the JAVADOC TAGS
   
  

 

File Comment Block:

 

Every source code file (*.java) must have a Javadoc comment block just before the class declaration containing the course number, assignment number, name of the file and purpose of the file. One or two lines is usually sufficient to explain the purpose. In addition, you must add the author tag containing your name and the version tag containing the date the assignment is due. For example:

 

import javax.swing.*;

 

/**

* CS-12J Asn 3

* HelloWorld.java

* Purpose: Prints a message to the screen.

*

* @author Jane User

* @version 1.0 8/20/03

*/

public class HellowWorld {

 

The following tags must be used always:

• @author
  
• @version
  

 

Method Comment Block:

 

Every method must have a Javadoc comment block before the method. For example:

 

/**

* Read a line of text from the shell console.

*

* @return A String input by the user.

*/

The first line is a description of how to use the method.

 

Where appropriate, the following tags must be used:

 

• @param
  
• @return
  
• @throws
  

 

---

 

Outro:

 

So that was it, the basics of how to create properly documented easy to use and understandable code. For any other questions leave a comment dont use PM's thanks.

 

Since maxcheaters is the biggest leecher forum in history of mmo gaming i feel its better me share my stuff than someone else share it under the name of "MeIzPro" so to see what's going to be my next share or want to vote please visit my den over at max-leeching-s: click

[Vector]

Awesome share, +1 from me interpid.

[Intrepid1989]

im absolutely lolled at mxc calling mxb leecher forum thats just so stupid :D

[Intrepid1989]

post hide taken off.

[pipiou21]

Thanks Interpid, i shall read it coz my coding is not that bad but the way im doing it it makes it dirty... !

[ArkeyWave]

im absolutely lolled at mxc calling mxb leecher forum thats just so stupid :D

this people doesn't deserve this knowledge [or the facking way this should be written]

 

let's go back home e.e

xD

[Sirpaypi]

Very useful guide, +1 from me.

[adenaman]

nice thread for more info, l2j use this coding style http://javolution.org/doc/coding_standard.txt

[`NeverMore]

Nice Guide dude...! Thanks for sharing