You can think that this title is funny, because the subject seems to be simple and basic, but believe me, there is a lot of people that has doubts about how comment the code, a lot of people that don’t use (and them should) the comments, some people that doesn’t know what it is or never seen.
If you fit into one of the profiles above, or not, you can be interested on the utility that the code comments have to us, programmers.
Believe or not, we can consider the comments like one of our best friends when the subject is programming. A comment has the objective of documenting the wrote code, so that in the future you know what that code does, and why it does. And it helps on the code viewing too.
We can think that doesn’t has need to comment a code, because at the moment that we are writing the code, everything is clear and fresh on our mind. But the problem comes my friend, when after some months, you have to do “some updates” in the code.
What you see is a tangle of words, and it’s really complicated to find something there. And if you find what you want… you don’t know how it works, because the code is very large and you will expend hours trying to figure out where you have to edit, or because it doesn’t explains itself enough.
That is where our friend comes. If the code is well commented, the viewing will be better (because the code isn’t squeezed) and you will have an explanation of what that piece of code do.
There is three types of comments in most languages: line comment, multi-line comment, and the last, asdoc, similar to javadoc.
The line comment (//) is the simplest, and, one of more used. It serves to simple comments, normally to comment one line of code.
Let’s see the following bit of code:
1 2 3 4 5 | public function startup(application:BaseApplication):void { Debugger.showMessage("Application Pre-initializing", Debugger.PROCESS); this.sendNotification(ApplicationFacade.PREINITIALIZE, application); } |
If you don’t know the code very well, probably you will not understand this bit of code.
With the code lines properly commented, is easy to understand what’s happening.
1 2 3 4 5 6 7 8 | public function startup(application:BaseApplication):void { // Showing message on debugger. Debugger.showMessage("Application Pre-initializing", Debugger.PROCESS); // Notifying the system that the application is been initialized. this.sendNotification(ApplicationFacade.PREINITIALIZE, application); } |
Obviously, if your comment isn’t good enough, it’s waste of time.
As you can see, the line comment type starts with //, occupies just a line, and is very useful to comment code lines and small bits of code. I always use the line comment type on my code, line by line. It seems to be exaggerated, but it helps me a lot, and my co-workers too.
The second type of comment, the multi-line comment, occupies more than one line, and is very useful to make long descriptions about a specific bit of code.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 | override public function execute(notification:INotification):void { // Showing message on debugger. Debugger.showMessage("ApplicationStartup command executing...", Debugger.PROCESS); /* Registering the ApplicationProxy, responsible for get the information's about the application loading process. */ this.facade.registerProxy(new ApplicationProxy()); // Getting the registered proxy. var proxy:ApplicationProxy = this.facade.retrieveProxy(ApplicationProxy.NAME) as ApplicationProxy; // Monitoring the loading process. proxy.watchApplicationLoading(notification.getBody() as BaseApplication); /* Registering the BaseApplicationMediator, responsible for the management of the interface components. */ this.facade.registerMediator( new BaseApplicationMediator(notification.getBody()) ); } |
The multi-line comment, how you can see, starts with /* and only finishes when it finds the */. All text that’s between the /* and */ will be considered a comment. With it, we can comment our methods too.
The third and last type of comment, is known like ASDoc. ASDoc is a tool for documenting an ActionScript code. That tool reads the classes, and through a specific type of comment, creates a documentation of that class.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 | package app.controller { import app.BaseApplication; import app.model.ApplicationProxy; import app.utils.Debugger; import app.view.BaseApplicationMediator; import org.puremvc.as3.interfaces.ICommand; import org.puremvc.as3.interfaces.INotification; import org.puremvc.as3.patterns.command.SimpleCommand; /** * The ApplicationStartupCommand class, prepares the data and visual elements required to * the application startup. * * @author Mozart Petter */ public class ApplicationStartupCommand extends SimpleCommand implements ICommand { /** * Executes the ApplicationStartupCommand. This method is called by the system. It's starts * the <code>Proxy</code> of the application, and registers the <code>Mediator</code> * responsible for the viewing. * * @param notification <code>INotification</code> object received by the system, containing * the sent notification. * @return void */ override public function execute(notification:INotification):void { // Showing message on debugger. Debugger.showMessage("ApplicationStartup command executing...", Debugger.PROCESS); /* Registering the ApplicationProxy, responsible for get the information's about the application loading process. */ this.facade.registerProxy(new ApplicationProxy()); // Getting the registered proxy. var proxy:ApplicationProxy = this.facade.retrieveProxy(ApplicationProxy.NAME) as ApplicationProxy; // Monitoring the loading process. proxy.watchApplicationLoading(notification.getBody() as BaseApplication); /* Registering the BaseApplicationMediator, responsible for the management of the interface components. */ this.facade.registerMediator(new BaseApplicationMediator(notification.getBody())); } } } |
Very similar to the multi-line comment, right? The tiny difference, is that an ASDoc comment starts with /** and ends with */.
The documentation generated by the ASDoc tool is on the same format of the Flash/Flex/AIR documentation. There are some IDE’s like the FlashDevelop, that have a native ASDoc generator.
That’s it folks, I hope you enjoyed, and that you guys now start to comment your code (or the boogie man will get you), making it very clear and easy to understand.