Archive for July, 2008

Documentation is a very important aspect in writing programs. Coders like to code; coders don’t like to write. It’s no secret that thorough and approachable documentation is a rarity in the coding world. Despite its necessity for the adoptability of a given software package, finding Sorry to say this folks, but employees leave. They get better jobs, or get fired, or for some reason or another leave your organization. By having your coders maintain well written documentation you give yourself two advantages:

  1. You protect yourself against workers leaving with legacy application knowledge, and
  2. You shorten the ramp-up time of the new employees that take over the application.

You should always imagine that you are working within a group of people, and each one of you should be able to understand each other’s code in a matter of seconds. Even if you decide to read your own code after a few months, it is nearly impossible to do so without proper documentation.

After reading this we know the necessity of documentation. But before documenting of our code we must set the structure of documentation that are acceptable to clients and how can someone other than me can understand my code without going into much details about the code.

Lots of tools are also available for documentation of code. These tools work correctly if we are commenting our code in a desired format that tool support. If we are talking about ‘ActionScript’ code documentation than most of the tool support JavaDoc commenting style. So we must follow certain rules in our doc comments.

  1. Rule #1 : Who has a doc comment
    Every declaration of a non-private interface, class, constructor, method or field must have a doc comment immediately before it.
  2. Rule #2 : First sentence
    The first sentence of each doc comment should be a summary sentence, containing a concise but complete description of the declared entity (class, method, whatever) being documented. This sentence must end with a period followed by a newline. However, this sentence may span multiple lines and may be followed by additional sentences. For example:
    * The JavaEyes class is a Java-based implementation of the
    * familiar "xeyes" program, available on many Unix-based systems.
    * Each JavaEyes object is a pair of "eyes" whose eyeballs
    * follow the movement of the mouse.
  3. Rule #3 : Required Tags
    There are special tags that can be used in Javadoc to indicate that a specific type of information is about to be given. There are many tags, but we require only these:
    • @author   name
    • @param   parameter-name   parameter-description
    • @return   return-description
  4. Rule #4 : Order of Tags
    Include block tags in the following order:

    * @param       (classes, interfaces, methods and constructors only)
    * @return      (methods only)
    * @exception   (@throws is a synonym added in Javadoc 1.2)
    * @author      (classes and interfaces only, required)
    * @version     (classes and interfaces only, required. See footnote 1)
    * @see        
    * @since      
    * @serial      (or @serialField or @serialData)
    * @deprecated  (see How and When To Deprecate APIs)

  5. Rule #5 : Placement of tags
    All tags should begin at the start of a new line of a doc-comment, per the examples above.
  6. Rule #6 : html
    You may use html tags (like <code> xxx </code>) within the doc comment to provide additional formatting of your comments. Not all html tags will work, but the most common will.
  7. Rule # 7 : additional content
    You may put comments into your program that are not doc comments. While the doc comments form the official public release documentation, other documentation may be useful during development.

Here is the example of commented code.

* Sets the position of the target object to a specific x,y location on the screen
* @param xPos The horizontal position on the x axis to place the target
* @param yPos The vertical position on the y axis to place the target
* @throws IOException If an input or output exception occurred
* @see moveTargetBy
* @see public function repositionTarget(Void):Void
* @return True if the positioning is successful, False otherwise
public function positionTarget(xPos:Number, yPos:Number):Boolean {
    // function body

All listed commands are very powerful for handling system configuration, process, network etc.

  1. fc : Compare two files and display the differences.
  2. fsutill : Powerful commands that can be used to configure many file system properties.
  3. getmac : Display the MAC address for your network card.
  4. icacls : Display or changes the access control list (permissions) for files.
  5. ipconfig : Display and change your TCP/IP configuration settings, to flush DNS or renew DHCP leases.
  6. net : A set of commands for interacting with Windows network functions.
  7. netsh : Powerful utility that can adjust many network and interface settings.   
  8. netstat : Displays immediate networks stats, such as open ports and routing table information.
  9. path : Set the path used by Windows for finding files without having to type the full path of a file.
  10. pathping : Used for network troubleshooting.
  11. reg : Interact with the registry from the command prompt.
  12. sc : Useful for configuring services.
  13. schtasks : Schedule tasks.
  14. set : Display or change environment variables.
  15. sfc : System File Checker, used to check whether system files are valid or not.
  16. shutdown : Shutdown the computer, optionally restarting if specified.
  17. start : Start a new application separate from the current session.
  18. subst : Map a folder to a drive letter.
  19. systeminfo : Show detailed info about the computer.
  20. tasklist : Display a list of processes with their IDs, useful in conjunction with taskkill.
  21. taskkill : Used to kill processes.
  22. tracert : Used for troubleshooting network connections by tracing through the route to a server.
  23. tree : Display the directory structure in an ascii-style tree.
  24. type : Show the contents of a text file.
  25. xcopy : Copy command that also copies subdirectories and files.