Comments on: Best Practices Checklist

By: Abdul Qabiz

Abdul Qabiz — Fri, 09 Feb 2007 18:35:40 +0000

When I talked about those long comment blocks, I meant Flex framework for example :-)

It depends team to team, developer to developer…Sometimes there are different opinions within team so people end up with something workable common…

-abdul

By: Peter

Peter — Fri, 09 Feb 2007 18:12:44 +0000

Abdul, good points — one of the things I hate about auto-generated docs is that it promotes this absurdly long commenting style.

I’ve seen too many projects that try to mimick adobe livedocs for each and every method, resulting in more comments than actual code in a class.

In my view comments are aimed at developers, documentation is a full text description that somebody like your project manager could grasp the jist of :)

By: Abdul Qabiz

Abdul Qabiz — Fri, 09 Feb 2007 17:59:50 +0000

Comments are really important. These days, documentation is generated from code. It has become generally practice to keep big blocks of comments with all those common comment elements so that documentation team, if you have one, doesn’t have to write everything from scratch rather they focus on description etc.

I believe, such comments doesn’t help much to a developer who is walking through code. Good code (method name, signature, clear responsibility per method/class etc) speaks in itself. Sometimes, developers use tricks/hacks or sometimes code path is different based on context (params, conditions etc) , I like those to be commented (@private ?) for another developer who would deal with code in future. I don’t assume that I would be only person dealing with code. That’s I try to clean up (comment, names etc) code by refactoring to make it easy (formatting, naming-convention, less-use-of-non-standard things or hacks etc) to understand and intuitive to other developers…

Commenting about platform specific hacks/tricks is really useful for developers new to platform (Flash Player etc)…

By: Ryan Taylor

Ryan Taylor — Fri, 09 Feb 2007 03:37:13 +0000

Peter,

Knowing when and where a comment is necessary is subjective; what’s obvious to you might not be obvious to somebody else. It’s simply a good habit to be in and other programmers will certainly respect you for it.

By: Peter O'Brien

Peter O'Brien — Thu, 08 Feb 2007 23:01:13 +0000

I’m surprised by Ryan’s and oz’s comments on commenting. I never think I need to teach actionscript. I like to be as precise as poss in putting the odd line in saying whats going on, and when something is not obvious, that’s when commenting is IMO worth a great deal – to both yourself at a later date (5mins or 5days) and everyone else who might have the experience of reading and following your code.

Something I’ve recently started to do is to simply list events dispatched by the class at the top, for example like so:

[Event] onItemAdded {item}
[Event] onItemRemoved {item}

I’ve found this commenting technique really help above everything else I use or have tried.

By: oz

oz — Thu, 08 Feb 2007 06:37:48 +0000

Thanks for the tips guys. This really helps.

Ryan: “…a good commenting practice is to pretend like you are writing and commenting code for somebody that is learning the language.”

I couldn’t agree more. I try to follow this approach for code that I post online. For code at work I comment for my own elucidation and that’s about it. I should really get better at that.

By the way, one of the funniest comments I ever read was from a dev that left before I started working at Xbox. It basically said, “All this code is crap. If you need to make changes to this project then just start over. It will save time.”

I appreciated the honesty.

By: Ryan Taylor

Ryan Taylor — Thu, 08 Feb 2007 03:02:37 +0000

Commenting is actually the one area that I think most developers need improvement in the most. It’s frustrating to me when I pop open a class file only to find that each method has a massive paragraph of Javadoc-ready commenting. Beyond the fact that the method’s commenting and documentation are the same thing, the developers that comment like that also tend to neglect the code inside the method itself. To me, a good commenting practice is to pretend like you are writing and commenting code for somebody that is learning the language. Not only will the developers that look at your script later on appreciate it, but months down the road when you have to revisit it for whatever reason, you will certainly thank yourself as well.

Documentation -> How and why you use it.
Commenting -> How and why it works.

Great post though; I definitely agree with each of those practices.

By: Peter

Peter — Thu, 08 Feb 2007 02:10:39 +0000

Some great additions Abdul — absolutely agree there!

I generally also recommend using TODO, FIXME notes in the code with the developers initials and references to a bug id for team projects.

Also worth writing interfaces for any generic base classes that are used throughout multiple projects. Just helps in narrowing down any possibly issues and makes sure you have a solid implementation.

Will probably think of some more, its a really good exercise to consider these things even if you don’t end up using every single best practice.

By: Abdul Qabiz

Abdul Qabiz — Thu, 08 Feb 2007 01:22:37 +0000

There are some more things, that can be considered in Flex/AS3 context:-

1) Proper packaging structure for MXML and AS3 components, util classes and other libraries are important. Needs to be documented, so that team knows where to find things and not to duplicate things if it exists already. Saves loads of time over the time..

2) It’s good idea to come up convention to give ids to MXML tags and a guidelines so that designers (using FlexBuilder) follow that.

3) If #2 is followed consistently, it would allow to keep AS code in include file instead of MXML, this avoids any kind of mishaps in code if MXML is changed (layout etc) by someone else. I agree, version-control saves you from that…but having code outside gives you more control over things in terms of Version-Control :)

4) For a big team, it makes sense to create templates for different things (AS3 components, MXML components, Modules etc). This allows to quickly create things from templates without including the namespaces, includes etc…

Thanks Peter for posting this, this got me thinking about the practices…I would think more realistic and practical things and update here :)

-abdul