bagustris@/home: Project Naming / Penamaan Proyek (file, variable, identifier)

Saturday, May 25, 2013

Project Naming / Penamaan Proyek (file, variable, identifier)

While there are plenty of projects that fail with descriptive names and plenty that succeed without them, I think naming your project is worth giving a bit of thought. Leslie Orchard tackles this issue in an Advogato article (http://www.advogato.org/article/67.html). His article is short and definitely worth looking over quickly.

The synopsis is that Orchard recommends you pick a name where, after hearing the name, many users or developers will both:

Know what the project does.
Remember it tomorrow.

Humorously, Orchard’s project, “Iajitsu,” does neither. It is probably unrelated that development has effectively frozen since the article was written.

He makes a good point though. There are companies whose only job is to make names for pieces of software. They make a ridiculous amount of money doing it and are supposedly worth it. While you probably can’t afford a company like this, you can afford to learn from their existence and think a little bit about the name you are giving your project because it does matter.

If there is a name you really want but it doesn’t fit Orchard’s criteria, you can still go ahead. I thought “gnubile” was one of the best I’d heard for a free software project ever and I still talk about it long after I’ve stopped using the program. However, if you can be flexible on the subject, listen to Orchard’s advice. It might help you. [1]

"C" File Naming Convention

File names are made up of a base name, and an optional period and suffix. The first character of the name should be a letter and all characters (except the period) should be lower-case letters and numbers. The basename should be eight or fewer characters and the suffix should be three or fewer characters (four, if you include the period). These rules apply to both program files and default files used and produced by the program (e.g., "rogue.sav")[2].

Rules for constructing variable name (in programming) [3]:

Characters Allowed :

Underscore(_)
Capital Letters ( A – Z )
Small Letters ( a – z )
Digits ( 0 – 9 )

Blanks & Commas are not allowed
No Special Symbols other than underscore(_) are allowed
First Character should be alphabet or Underscore
Variable name Should not be Reserved Word

Rules for writing identifier [4]

An identifier can be composed of letters (both uppercase and lowercase letters), digits and underscore '_' only.
The first letter of identifiers should be either a letter or an underscore. But, it is discouraged to start an identifier name with an underscore though it is legal. It is because identifier that starts with underscore can conflict with system names. In such cases, compiler will complain about it. Some system names that start with underscore are _fileno, _iob, _wfopen etc.
There is no rule for the length of an identifier. However, the first 31 characters of an identifier are discriminated by the compiler. So, the first 31 letters of two identifiers in a program should be different.
Choose a meaningful name for an identifier, it will be easy to understand and work on.

Standard date notation

Sometimes, we named our file or directory with a date (or time). What is the standard writing of date? According to ISO ( ISO 8601), the international standard date notation is

YYYY-MM-DD

where YYYY is the year in the usual Gregorian calendar, MM is the month of the year between 01 (January) and 12 (December), and DD is the day of the month between 01 and 31 [5].

For example, the fourth day of February in the year 1995 is written in the standard notation as

1995-02-04

It is clear that it is more readable than format

19950204

Although both formats are accepted. Readable count, guys!

(Python) Variable Naming

Some tips on naming variables:

Use Names Which Reveal Intention (if a name needs comment, it doesn't reveal the intention)
Avoid Disinformation (e.g. don't name it ProductList if the type does not list)
Make Meaningful Distinctions (use data vs target instead of X, y (but it commons in machine learning)).
Use Names You Can Pronounce (data instead dt)
Don't user Member Prefixes (e.g.: _myClass)

Dash or underline

When facing a doubt for using dash (like-this) or underline (like_this), there is a rule of thumb,

If this name will appear online or the name of a directory, like GitHub project or URL, use dash. The search engine will easily find it,
If it is the name of a file, use underline. The reason is it is more readable for humans,
if it is variable in codes, it should use an underscore.

--------------------

tl;dr (Too long; didn't read.): Penamaan Proyek (termasuk file, direktori, dll)
Ada dua konsep sederhana dalam memberi nama sebuah proyek (Apps, web apps or others, especially open source projects).