Thursday, September 02, 2010

My own naming convention and what problems could arise from it

Hi, developers!

We write applications and our applications use data. We create data, edit data, store data...
Sometimes we store data on the File System. And I think that's a common practice.

Have you ever wondered how to name your files in order, not to have naming collisions or creating some temporary files with some extensions, only you as a developer, should know about ?
Have you ever encountered exceptions in your code while accessing the file system? A glitch in your code maybe?

I am going to address this issue because it's sometimes regarded as a trivial task and everybody is said to do it the right way.

1. Create states in your program 

If at runtime your program has some strict set of states that it is in, then you can be calm and happy about your design. If you can keep the state of your variables consistent, you can manipulate them as you wish and not fear some collisions. What I mean is when you invoke a method, it knows exactly what to expect - whether a String that is passed as a parameter could be null, or if it is in a special internal format, etc...

Entering methods and exiting from methods must keep the representation invariant intact and everybody should know their role in the process.

2. Keep the number of states of your program low
If you apply rule no.1, you can still mess up, if you have like ... 100 different states. Your head will be full of conditions and rules to transit from one state to the other...

 A developer should not think about more than 7 things while developing. That way he can stay focused and make always the best decisions about his design.

3. Document your states

Be honest about your program's states. Tell your colleagues. Don't be shy or overprotective , if there's this colleague who always critisize your code. If they know about the states you introduced, then they could tell you about a problem earlier and adopt those states in their modules early on.
Not to mention that at one happy moment, somebody else different from you will be supporting this code.

4. Avoid tricky (smart) code

I've seen smart code and it lead to invisible problems, reported and fixed years after the code was written and got into the final product.

- Imagine the following situation - you are passed String with the name of a file, and you must create your own temp file, where you should store your temporary data during the processing of the original file. So you create a file with

String tempName = originalFile + "temp";

And later you decide to wipe all those temp files, but since you have added "temp" at the end, you can just use
if ( "temp".equals(String.lastIndexOf(aFileName) ) {...deleteFile(); }

And you thought you deleted your files. What happens if there are files that are called "xxxtemp" by the original user? Even if you add "temp" at the end , you will get to delete both the temp and the original.

- Another smelly situation - your use case is to keep the temp files and delete all non-temp-ending files.
Ok so lets use:

fileName.replaceAll("", "temp");

So we'll discard the temp and we'll automatically get the original filename...
Wrong! What happens if all this is happening in directory "c:\temp\myfiles" ? You will get invalid file paths and another exception is thrown.

You should be very careful with these kind of situations with files.
I suggest 2 ways to avoid problems:

A) store in a collection the original files and in a new collection the references to the temp (new) files.
That way you don't need to think of weird algorithms to find temp/original files by their derivative's names.

B) if you have to think of such an algorithm be sure that it finds exactly what you want.
Back to the example with the replaceAll():
int lastIndex = fileName.lastIndexOf("temp");
fileName.replace("", "temp", lastIndex);

And this is exactly the opposite of string += otherString.

I am sure other developers have found other techniques to avoid problems but those were mine.
Feel free to share your opinion.

Leni Kirilov

No comments:

Post a Comment