Archive for the ‘Best Practice’ Category


AS2Doc
AS2Doc is a powerful, easy to use and fast documentation generator for your ActionScript 2 based classes. AS2Doc reads your source code, included comments and creates a rich content documentation automatically! You can choose various options to customize your documentation. Various output formats are supported by using AS2Doc Styles (XSL). You can even write your own style for any custom output format!

Online Page: http://www.as2doc.com/

AS2Docular v0.9.6
AS2Docular is a free, web-based application used to generate HTML documentation for Flash ActionScript 2.0 (.as) files. Like other tools of its kind, it uses ActionScript comments and code to decide the content of the documentation generated. For more on correctly commenting a file for AS2Docular, see Commenting ActionScript for AS2Docular. AS2Docular also support predefined template for documentation style. The best part of this tool is easy to use.

Online Page: http://www.senocular.com/projects/AS2Docular/standalone.php

ZenDoc
ZenDoc is a simple, free, (primarily) web-based application written in PHP used to generate customizable HTML documentation for Flash ActionScript 2.0 and ActionScript 3.0 source files. Like other tools of its kind, it uses Javadoc-style comments within source code to decide the content of the documentation generated.

Online Page: http://www.zendoc.org/zendoc/

ACID
ACtion Info Doc, (Acid), is written in Python, for ActionScript2 class api-doc generation. Include command-line script (acid) and GUI (wxAcid).  AS2 class analysis, grab info of the super, interface, constructor, properties and methods. Support most javadoc tags with some variants.  Supported Tag are for class, @author, @version; for properties, @throws; for methods, @param, @return, @throws; general, @see.

Online Page: http://icube.freezope.org/acid

VisDoc
VisDoc generates html documentation from ActionScript 2.0, 3.0 and Java class files. VisDoc integrates a smart processor to parse class files – you don’t need to prepare or rewrite your classes. Even if you don’t use doc comments, you can generate handy class documentation with a Table of Contents.

VisDoc is only available for Mac Os.

Online Page: http://visiblearea.com/visdoc/

AS2API
AS2API parses ActionScript 2 source code and generates HTML API documentation in the style of JavaDoc. It is open source, and runs on Windows, MacOSX and Linux.

For ‘FlashDevelop’ (ActionScript Editor) user has a best option to use AS2Doc. FlashDevelop already configured with AS2Doc tool.

Step to use AS2Doc in FlashDevelop:
step1
1. Tools -> Flash Tools -> AS2API
2. Enter Documentation Page title in <Page Title> field.
3. Enter Package name to be documented in <Package> field.
4. Enter output dir path where documentation to be created in <Output Dir>.
5. Select classpath of package to be documented using <Brows> option.
6. Click on <Generate Documentation> button for generate document.

Online Page: http://www.badgers-in-foil.co.uk/projects/as2api/

 

🙂


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
}


1. Don’t write deeply nested code
It is bad programming style to write deeply nested code – the code has a tendency to drift across the page to the right and soon becomes unreadable. Try to limit most of your code to a maximum of two levels of indentation. This can be achieved by dividing the code into shorter functions.

2. Don’t write very large modules
A module should not contain more than 400 lines of source code. It is better to have several small modules than one large one.

3. Don’t write very long functions
Don’t write functions with more than 15 to 20 lines of code. Split large function into several smaller ones. Don’t solve the problem by writing long lines.

4. Don’t write very long lines
Don’t write very long lines. A line should not have more than 80 characters. 
Example:
if(objHideRevealPalette.tree["paletteButton.textHideIcon"].getSelected() || objHideRevealPalette.tree["paletteButton.textRevealIcon"].getSelected())

Write above line like this:
var bHide:Boolean = objHideRevealPalette.tree["paletteButton.textHideIcon"].getSelected();
var bReveal:Boolean = objHideRevealPalette.tree["paletteButton.textRevealIcon"].getSelected();
if(bHide || bReveal)

5. Variable names
Choose meaningful variable names – this is very difficult.

6. Function names
The function name must agree exactly with what the function does. It should return the kind of arguments implied by the function name. It should not surprise the reader. Use conventional names for conventional functions

7. Format programs in a consistent manner
A consistent programming style will help you, and other people, to understand your code. Different people have different styles concerning indentation, usage of spaces etc.

For example you might like to write tuples with a single comma between the elements:
{12,23,45}

Other people might use a comma followed by a blank:
{12, 23, 45}

Once you have adopted style – stick to it.
Within a larger project, the same style should be used in all parts.


All we are a good programmer but we need to avoid thinking these points when we are writing code.

  • It compiles, so it works.
  • It works here, so it works everywhere.
  • Commenting? We don’t have time to waste!
  • UML diagrams are useless.
  • Plan code so that we can reuse it is useless: we’ll end up writing everything from scratch anyway.
  • Unit tests are a waste of time.

Thanx for reading this but now we need to rethink on our code.

    How to write good code

    Posted: June 2, 2008 in Best Practice
    Tags:

    Having been coding as a programmer, we have seen and write a lot of bad code. Code is not good just because it works. So here’s a quick list of that we would better keep in mind while coding.

    1. Don’t sacrifice code maintainability to performance, unless it’s strictly necessary.

    This happens very often. You have to consider that your code is likely to be read by many persons, and some of them will read it after you might have parted from that company. Remember that you won’t remember what your own code does after few weeks. So always try to put things in the most readable and obvious form, even if this will require writing more lines of code, or having less performing code. Of course this is not so important if performance is your number one issue. Try, for instance, to avoid use of the ?: operator everybody will understand it anyway, but a good old if statement will do it, so why not going for it?

    2. Be precise as a Swiss clock, when it comes to naming conventions.

    Nobody wants to read class names or variable names that look like gibberish. Don’t be mean on the keyboard: when we type, remember that somebody else will have to read it, so be extensive.

    1. Name our variable NumberOfItems rather than items_n. Don’t use cryptic prefixes to class name. Name our class ClientMessageOperationsBasicFunctor rather than CMOpFunctor. It’s a lot more typing for us, but a lot less hassle reading for the ones that will come after us.

    2. Don’t change your conventions. If we are calling the iterators i, don’t call any of them n, ever. You will induce confusion to your reader. It doesn’t seem as important as it actually is. If you call a class ClientMessageBlockContact, then do not have ServerMessageContactBlock. Be perfect, be precise, be obsessed.

    3. Use a good and consistent indentation style.

    Never ever have more than one blank line. Don’t have trailing spaces at the end of the lines. Don’t have blank spaces or TAB characters in blank lines. A blank line must be blank, that is.Be consistent: don’t use TABs to indent in one file, and spaces in another one. Possibly, use 8-chars wide TABs to indent. If you find yourself going beyond 80 rows too often, then that could be an indication that there might be some design flaws in your program. Tweak your editor to show you the end-of-line character and the TABs.

    4. Use TODOs and FIXMEs.

    If you know that you, or somebody else, will have to return on a certain piece of code to add or modify some functionality, please mark it with a TODO. If you know that a piece of code is buggy but you can’t fix it right now, add a FIXME marker. Later on, it will be easy to grep the source tree for TODOs and FIXMEs and analyze them, especially if they’re very well commented.

    5. Comment your own code.

    Seriously: you’re going to forget, sooner than you think. Just invest 5% of your time in writing commented code. Never assume that code is self-explanatory, just write a couple of lines for everything you do. Comments are not only meant to generate doxygen documentation. You have to assume that somebody else will read your code and need to modify/extend it.