Simon Wacker

I’m currently documenting all classes of the as2lib. Good documentation is often neglected in the world of ActionScript. Although it is very important. Thus here a few guidelines.

Why should I document code?
It’s quite easy to answer this question. Others too wanna know what’s going on or how they can use the code. And that without rummaging through all the stuff. But it’s also a help for you. Imagine you write a piece of code and years later you need to use it. You probably don’t know anymore how to work with it. And without good documentation you had to spend maybe an hour to just get the whole thing to work.

How do I document?
There exist a few standards. These standards are actually from a Java background but you can use them in every language. It’s important to pay attention which standards you documentation tool uses to extract the documentation properly.
The follwing link may be useful: http://java.sun.com/j2se/javadoc/writingdoccomments/.
Let’s start:

The Basic Construct:
/**
*
*/
That’s the basic construct. You probably know it. Just use it for every doc comment.

Block Tags:
Block tags are tags preceded by an @. The one you do probably need at most are: @param, @return, @see, @throws, @author and @version. There do exist more. You can find them with a big description under the link I posted above.

How a Doc Comment is Made Up:
/**
* [description]
*
* [block tags]
*/

Example:
I’ll just use the example from the above link because it is (almost) perfect:

I’m sorry for the bad design (no spaces etc.) but MovableType screws the whole thing up. If you know how to fix it let me know.
[Edit]The spaces work now. At least in the example.[/Edit]

AspectJ is a programming language that enables you to write Aspect Oriented code for Java. The terms I’m going to explain in this article probably apply to every other Aspect Oriented language but I’m going to give examples in AspectJ code. Let’s start:

You describe with AspectJ where to weave in the crosscutting logic and what to weave in. To do this you need at first identifieable points called join points.

Join Point
“A join point is an identifiable point in the execution of a program”. A join point is quasi everything within your class. For example a call to a method, an assignment to an instance variable and so forth. These join points represent the places where the crosscutting logic can be woven in. Join points do reside in classes.

Example:
public class MyClass {
…
public void doSomething(int parameter) {
instanceVariable = parameter;
}
}

The join points in this class are the execution of the doSomething method as well as the assignment of the variable instanceVariable.

Aspect
The aspect is the main construct of your aspect code. You can compare it with a class although there are varieties.

Example:
public aspect MyAspect {
}

Pointcut
You somehow need to select a join point in your aspect. You do this with a pointcut.

Example:
execution(void MyClass.doSomething(int))

You now capture the execution of the doSomething() method in the class MyClass. But you also want to execute code when the execution takes place. Thus you need an advice.

Advice
“An Advice is the code to be executed at a join point that has been selected by a pointcut”. You have different opportunities when the execution shall take place: before, after or around the join point.

Example:
before() : execution(void MyClass.doSomething(int)) {
System.out.println(”The doSomething() method will be executed.”);
}

Example that sums everything up:
public class MyClass {
private int instanceVariable;
public void doSomething(int parameter) {
instanceVariable = parameter;
}
}

public aspect MyAspect {
before() : execution(void MyClass.doSomething(int)) {
System.out.println(”The doSomething() method will be executed.”);
}
}

If you now compile the aspect MyAspect the System.out.println() call will be woven into the code of the class MyClass. The result would decompiled probably look like the following:

public class MyClass {
private int instanceVariable;
public void doSomething(int parameter) {
System.out.println(”The doSomething() method will be executed.”);
instanceVariable = parameter;
}
}

Okay that are basics for now. The next article will go more in depth.

How to name classes, packages, methods, …. . Everything needs a name. That’s the problem I’m facing every day and I think every programmer does. There seems to be no book that deals with that issue. Or at least I haven’t found one. So what does the internet hands over.
If you search on java.sun.com you’ll probably find the basic stuff like this: Code Conventions but isn’t there greater help out there?
A really helpful article I found next was on hacknot.info: Naming Classes - Do It Once And Do It Right.
And then I stumbled over a kind of ultimate guide: AmbySoft - Coding Standards For Java.
The articles are obviously good but they aren’t perfect now. I’d really appreciate a good book that only deals with the issues of naming. It shouldn’t define standards and say: “That’s the truth!” but reflect different possibilities and show the advantages as well as the disadvantages of each.
I hope such a book will be available for novice programmers some day.
Maybe I’ll write one myself.