Naming stuff...

[fx.barrett]

I'm really curious to see how you guys name your variables and functions... I've been troubling with this for a while and I've been changing my coding style every 2 months because of this and I had enough, I want to know how others do this:

For example, we have a class that has a private variable in it and I want to define a getter and setter method that will help me manipulate my data ( variable )... the stupid thing about ActionScript is that I can't name the function the same way as my variable... so I hate 2 options: give a different name to the function, or a different name to the variable... but in certain cases it's just stupid... example:

package com.wisebisoft.data
{
public class Time
{
private var hour:uint;
private var minute:uint;
private var second:uint;

public function Time(hour:uint, minute:uint, second:uint)
{
this.hour = hour;
this.minute = minute;
this.second = second;
}

public function get hour():uint
{
return this.hour;
}

public function set hour(value:uint):void
{
this.hour = value;
}

public function get minute():uint
{
return this.minute;
}

public function set minute(value:uint):void
{
this.minute = value;
}

public function get second():uint
{
return this.second;
}

public function set second(value:uint):void
{
this.second = value;
}

public function clone():Time
{
return new Time(this.hour, this.minute, this.second);
}
}
}
Obviouisly, that will throw an error... I see people using underscores for private variables but I really don't like underscores, I'd rather go with using "this." but then, I run into this naming problem... IMHO, it would be weird to name my private var from hour, time and minute, to initHour, initTime, initMinute or whatever name you want just to get rid of this conflict... likewise, it would be really bad to start thinking about names for the functions... and as I said, no underscores...

So, how do you guys name your stuff? How do you handle this annoying naming conflict?

Thanks a ton.

[fnx]

That's one of the reasons why I don't use getters and setters :P

Anyway, if you don't like underscores (me neighter) you can do something like that
for private variables:

p_hour, pHour, prHour, hour_p, hour_pr... and so on

I use p obviously to indicate private while the getter and setter stay the same.

Just my 2 cents :)

[fx.barrett]

Yeah, that would be an option... but I kind got bored of using that :) Anyway, thanks for the feedback, appreciate it. ;)

[pj-co]

In my opinion the way you name you private variables isn't really all that important. People get too hung up on this detail. Personally I just add an _underscore if, and only if, I have a getter or setter. FlashDevelop does this when it auto-generates getters and setters too. Getters and setters absolutely have a use too. Whether you like to use getSomeProperty() or get someproperty { return _someproperty} is up to you, but I have to disagree with fnx that they should be avoided for not liking underscores.

What's more important (in my opinion) is language convention. I'm not sure if you code in English or not but this is something I do for my code in English.

1) all variables/properties should be named with a noun when possible.

examples:

width
height
children


2) functions/methods should be named with a verb that describes what the function does.

examples:

closeAllDoors();
resetInitialProperties();
moveLeft();



3) Nothing should be abbreviated that isn't an industry-wide common abbreviation. This is very important for people learning to code and people reading your code who may not speak your language very well. Also, it helps those who may just use a different set of abbreviations for things. It also improves readability for reasons described in #4.

example:

clickSnd should be clickSound
vertLine should be verticalLine
moveL should be moveLeft


4) Don't use "Hungarian" type notation for variables. It's severely decreases readability because it puts some letters in there that aren't a word. Humans read words by "glancing" at the overall shape of a word then comparing that shape to their memory. Also, variables are already able to be strongly typed and that information is already provided via compile time errors and is auto generated by just about every IDE out there.

examples:

strFirstName should be firstName : String
numCurrScore should be currentScore : Number


Ultimately though all this has another, more important effect on your code: it creates code that is it's own documentation. You've probably heard the "self documenting" code mantra before but this is really how it's done. If things are well named, you can come back to old code and know what everything does at a glance.

example:


package
{
import com.exmaple.myflashapplication.media.VideoPlayer;

public class ApplicationManager
{

public function ApplicationManager ()
{
var videoPlayer : VideoPlayer = new VideoPlayer();

videoPlayer.flvURL ="myFLVfile.flv";

videoPlayer.autoPlayWhenLoaded = true;

videoPlayer.loopPlayback= true;

videoPlayer.load();

}
}
}

I'll bet you can guess what all of that would do, and where it would go. You probably already recognize all this too because these are guidelines Adobe/Macromedia used in coding Flex and the ActionScript language itself.

If you want to read more, have a look here:

http://opensource.adobe.com/wiki/display/flexsdk/Coding+Conventions

I don't agree with all of what they say but it's a good read for picking up some ideas about situations you may have wondered about and finding ideas for other stuff you may encounter.

[fx.barrett]

Thanks for the reply pj-co. I was aware of the naming conventions just that they never seem to cover the situation I was talking about. I too have been using underscores in certain situations when dealing with getters and setter, all I wanted to know if there are any people out there who found a more elegant way of doing this...

I'm a perfectionist and in my opinion, it looks ugly when 80% of the variables are named without underscores and then we have 4 vars that use underscores... it might be confusing for someone who does not understand the way you write code. That's the main reason I started this thread, too see if anyone found an intelligent way of dealing with this problem but at the same time keep the code readable and easy to understand.

[pj-co]

Thanks for the reply pj-co. I was aware of the naming conventions just that they never seem to cover the situation I was talking about. I too have been using underscores in certain situations when dealing with getters and setter, all I wanted to know if there are any people out there who found a more elegant way of doing this...

I'm a perfectionist and in my opinion, it looks ugly when 80% of the variables are named without underscores and then we have 4 vars that use underscores... it might be confusing for someone who does not understand the way you write code. That's the main reason I started this thread, too see if anyone found an intelligent way of dealing with this problem but at the same time keep the code readable and easy to understand.

Yeah I hear ya. I guess in some ways I actually like that. When you see 4 private vars with underscores then you know they have getters/setters. To each their own I guess :)

[fx.barrett]

Yeah, but it might not be as obvious to others. :) anyway, I think I'll change my style ( but this time finally ) and I'll start using underscores for private vars... if that's what people are used to, it's fine with me. :)

[pj-co]

I don't use _them _for _all _private vars, just vars with getters/setters :)

[fx.barrett]

I don't use _them _for _all _private vars, just vars with getters/setters :)
Nah, if I'll be using underscores then I'll use them for everything :)

[fnx]

... but I have to disagree with fnx that they should be avoided for not liking underscores.
...

In fact I wrote it's ONE of the REASONS :)

Anyway, I totally agree with you on all conventions, when I have to follow
the "best practice" I use _varName too, but, when I'm not forced to, I avoid
using getters and setters only because they enlarge my source for nothing,
I have plenty of functions that only return or set a value..

When I can code "my way", I set private vars only for vars used by the class
and public everything that must be seen "outside".

Never said that my approach is the right one :)

Cheers

[Vjeko]

I agree with pj-co, and I would just add something...

I use different first letter for private or public functions:

private:
myNewFunction()
public:
MyNewFunction()
This way you can tell difference when you see a function.

Also, always use "positive" context or "is" prefix when having Boolean variable, because it has more meaning that way.

And as research said, you spend more time reading your code than writing it. :D

Cheers,
Vjeko

[rawmantick]

1. Member sorting:

static public constants
static public methods
static public variables

static private constants
static private methods
static private variables

nonstatic public constants
nonstatic public methods
nonstatic public variables

nonstatic private constants
nonstatic private methods
nonstatic private variables

public class SomeClass extends AnotherClass
{
static public const NAME:String = "SomeClass";

static public function getInstance():SomeClass;

static public var instance:SomeClass;


static private const BG_COLOR:uint = 0x099009;

static private function buildInstance():void;

static private var _inst:SomeClass;


public function someMethod():void;

protected function onInit():void;

protected var _facade:ApplicationFacade;

private function initSubItems():void;

private var _object:Object;
}

I put static members first, because they refer to the class... I see some magic in that:)

I put methods first, because they reflect class instance behaviour and more important than variables being responsible only for that behaviour implementation.

I don't support the religion of putting vprivate variables first, because I think when someone looks at your code - he or she needs it's interface - methods...

Well, probably I'd change it so:

first sorting parameter is access (public/protected/private) and then relativity to class/instance (static/nonstatic).

I always try to bit myself keeping formatting according to this one...

I think it's a very good practice.

Well... maybe I should also name private and protected methods with underscore either...

[creynders]

I use different first letter for private or public functions:

private:
myNewFunction()
public:
MyNewFunction()
This way you can tell difference when you see a function.
Ow, man you shouldn't start your public methods with a capital, that's really confusing! Only classes should start with a capital, it's been like that since... Moses came down the mountain and wrote it in stone.

Anyway, I organize my members as follows:
static consts
static props
static accessors
static meths

constructor

instance consts
instance namespaces
instance props
instance accessors
instance meths

And I do not organize members by their accessibility. With any half-decent IDE you get an outline, so I think it has more of an added benefit to have the meths in a logical order, than by class member visibility

I use the constructor as a divider between the static members and the instance members, since that makes sense to me. If an instance is created a constructor is run, so it's logical that it's top of the instance code. (Oh yes, I always write a constructor even if it's empty)
To me the order of props, accessors, meths makes sense since to me accessors are something between props and meths. They are used like props but written as functions.

I used to underscore all private members, but I've stopped doing that. I only underscore the targets of accessor functions.
I always use "this" to refer to an inherited prop or meth (or if it's necessary of course) to me this reads a lot faster, since in many IDE's the inherited meths and props aren't outlined, so sometimes I start doubting whether something is a global function or an inherited method. By using "this" I don't have to doubt.

[Vjeko]

Ow, man you shouldn't start your public methods with a capital, that's really confusing! Only classes should start with a capital, it's been like that since... Moses came down the mountain and wrote it in stone.

Well Moses had crappy handwriting so I read differently. ;)

Anyway, I never had any hard time (or anybody else) reading the code this way... Also that's standard for C# naming so I took it. :)