Best Practices for File Organization/Project Explorer

[zenthoef]

So we are finally getting SCC at my organization to manage our LabVIEW development, and that is good! 

Now, we are starting in on discussions about how we should organize our files on disk and how we should use the Project Explorer. When I started here about 3 years ago, I wasn't very familiar with the project explorer, so I read the article at http://zone.ni.com/devzone/cda/tut/p/id/7197. Two of the main things I took away from that article are:

1. Organize Files in a logical manner on disk. Whatever that is, it is not a flat file structure.

2. The top level VI should be separate from other source code. Preferably, it should reside in the application folder.

Push Back Against These Recommendations

Before I was hired, most, if not all LabVIEW development was done utilizing a flat file structure and the top level VI lived with the source code. Since we didn't have a proper SCC, each individual organized files as he saw fit. So I started using the Project Explorer (not even its use is totally accepted right now) and I began follow recommendations 1 and 2 above. I didn't always follow #1 very strictly, but I have been working towards it, and I have always followed #2 religiously. 

Since we are starting these discussions on how we should organize files on disk I'm starting to get some push back to following these two recommendations.

The arguments I get in favor of using a flat file structure is that you always know where every file is; including the top-level VI. It is also argued that it is a lot of effort to organize and search for VIs when they all reside in different folders. I think the fear is that by getting "clever" and organizing our files in such a manner we'll make things complicated and we will somehow shoot ourselves in the foot. 

The argument I get against separating the top level VI from the rest of the source code is that it:

(a) Won't be clear where it is (like it is buried within hundreds of VIs). However, it is argued, you can just put a "!" in front of the file name and then it is always the at top of the flat file structure.

(b) An extension of argument of (a) is that things either look or seem messy when VIs (including top level VI) don't live in a sub-folder and are just hanging out with the Project Explorer file. 

(c) I think there may be some fear of breaking the VI by moving it and altering the dependencies for the VI. 

Convincing Others its Good to Follow These Recommendations

So, if I want to follow NI's recommendations, I need to come up with reasons we should follow these recommendations. Also, I should state that I care about following these recommendations because its what NI recommends. They've been around the block a few times and I'm sure there are good reasons why these are best practices. However, I don't think I've given a very compelling case for why these recommendations should be followed.

So I'll tell you all what I think good reasons are for these recommendations and perhaps I can get some feedback or additional support? If I'm crazy for wanting to follow these recommendations maybe someone can point out why I'm crazy. 

(a) Arguments for Following Both

I. I passed the CLAD a couple of weeks ago, and I have started studying for the CLD. Part of the CLD is following both of these recommendations (see page 6 of http://ftp.ni.com/evaluation/certification/cld/cld_exam_prep_guide_english.pdf). While this isn't a reason in and of itself, it suggests that if it important when being certified it is important in practice!

II. If we hire new developers that are familiar with LabVIEW, they will most likely be familiar with these recommendations, especially if they are certified. That will lead to increased productivity out of the door because they won't have to learn our special way of doing things.

(b) Arguments for Organized File Structure

I. Unused VIs are easier to identify and remove. Right now we never remove VIs because we don't know if they are used or not. This leads to a lot of VI bloat.

II. It is hard to know what a specific VIs function is in a flat file structure by looking at the name.

(c) Arguments for Separating Top Level VI from Source Code

I. Placing the top level VI is an intuitive place for this VI. As long as the top level VI is the only VI in the application folder there is no mistake it is the top level VI, especially once you open it. This makes it easy for new developers to find the top level VI. I'd argue it isn't very intuitive for new developers to know that a VI in the source code folder that is prefaced with a "!" is the top level VI.

Summary

So that is what I think so far. Is there anything else I am missing to support following those two recommendations or am I just being inflexible?

Thanks!

[zenthoef]

I thought of a couple more reasons to follow these recommendations after my first post. 

(a) Arguments for Following Both

III. Code maintenance. Easier to maintain your own code and code of other programmers.

IV. Related to (a) II, we are doing (hopefully) what the rest of the world is doing. That seems good.

(b) Arguments for Organized File Structure

III. Easier to practice code reuse with an organized file structure. As long as the code that is written is highly cohesive and loosely coupled. A good argument for using LVOOP? And define an API upfront so that we can use reuse libraries?

IV. Easier to test sections of code using NI tools such as Requirements Gateway, VI Analyzer, and Unit Test framework. (Test often and early!)

V. Code maintenance across developers is better managed.

VI. File structure will reflect design document specifications, so it will be easier to understand the code from reading the design document.

[soupy]

I don't really think that there is a right way. the most important rule is consistency. You will get the largest efficiency increase from all developers in your group by doing things in a consistent way. You can leave it up to the group to determine if that consistent way works or not.

[zenthoef]

bazookazuz - 

I don't disagree by doing things consistently, we will gain large amounts of efficiency. I suppose the issue is the group determining what is efficient and what is not. Half of us think the two recommendations above are good and the other half don't, and those opions are largely based on individual experience. 

[TomBrass]

zenthoef,

As a CLA, I have struggled with file structure over the years.  Here are my recommendations:

1.  Put the top level VI and the project in the top-level folder.  This makes it very clear where to begin.

2.  Put the remaining user interface VIs in a separate folder.  Again, it makes it very clear what the functionality of these VIs are.

3.  If you are using object, put each object in a separate folder.  Place the family of objects in one folder, with each object in a subfolder.

4.  Keep the remaining VIs either in a single folder.  This can contain a small number of subfolder if your project is large, but too many folders makes it hard to figure out where your VIs are.  For example, you might have a DAQ subfolder, an Analysis subfolder, and a Report subfolder.  But if you had a Test1 folder, a Test2 folder, and you had a VI that was used by both tests, where would it go?  Keep it simple.

5.  You inferred that it is hard to figure out what a VI does by its name.  That implies that 1) you need better names, and 2) your VIs are too complicated.  A VI should do a single function which can be adequately described by its name.  That VI might be something like Analyze Data.vi, which would contain a bunch more subVIs (like Get 1st Harmonics.vi), but each VI would contain a single function.  You wouldn't save the data to a report in the Analyze Data.vi, for example.

The most compelling reason for following these suggestions is that it is easier to figure out what the code is doing after you haven't looked at it for a while.  Once you have an application that is working and bug free, you shouldn't have to touch the code until you want to add features.  If that is even 6 months later, you will probably have forgotten how the code works.  As a consultant, I have had to update other people's code, and just figuring how where to start can be a challenge.

Tom Brass

Certified LabVIEW Architect

Saint Bernard Engineering, Inc.

www.saintbernardengineering.com