Four Reasons You Should Take Naming Conventions More Seriously

03/20/2013

Comments

So…let’s say you’ve developed a really cool, really complicated DataBlock. It has 5 forms, 15 multi-column list boxes, 20+ parameters and a dozen SQL variables. A month after it goes live, a director comes up to you and says, “This would be even more useful if the report had some changes.” In the time since you deployed your masterpiece, you’ve worked on several other DataBlocks, but now you need to revisit your pride and joy and make the requested changes. Unfortunately, you didn’t give any of the DataBlock elements a meaningful name. Now you’re stuck, poking through a huge list of variables trying to remember exactly what’s going on and which parameters need to be changed. Sound familiar?

If you’ve ever found yourself in this situation—either because you stick with default names or leave renaming until the end of your development process where it sometimes falls off the to-do list—then I’ve got an easy solution for you: naming conventions. For those of us frequently on a deadline, the temptation to leave the default names and keep moving is often strong. But even if it takes an extra moment, I highly recommend giving every DataBlock element a meaningful name, and do it as you go. Why? There are a number of reasons:

Reason 1: You win the lottery.
All right, so you’ve just won the big jackpot. You walk into work Monday morning and quit. Now, one of your colleagues has the thankless task of trying to pick up where you left off. If you have left the variables and parameters as the default, that person is stuck trying to determine which parameter goes on each form and what they each do.

Reason 2: You have more than one DataBlock in progress at a time.
Probably a more plausible scenario than the last, let’s say that, in any given week, your development time is spread across several projects at once. Constantly changing priorities, the weekly barrage of meetings and other disruptions can cause your work-in-progress list to shift daily, sometimes hourly. Putting a DataBlock down and picking it back up hours, days or even weeks later is more common than completing one in a single session. If you haven’t named anything, it will take some time—every time—to pick up where you left off.

Reason 3: You work on DataBlocks with multiple developers.
If you happen to work in an environment where developers hand projects off to other developers or share development time on a project, standard development procedures are a must-have. (This, by the way, should include not only naming conventions, but also documentation, comments and standardized user interfaces.) Having clear, intuitive names for everything speeds up the hand-off process considerably. The developer taking over knows exactly what to expect and can quickly come up to speed on the type, purpose and location of every element.

Reason 4: You don’t like repeating your work.
Although many developers leave naming until the end of their development process, as part of their documentation, doing this in Argos would be a very bad idea. Changing the name of a parameter AFTER you have built the DataBlock will not change every occurrence of that parameter within the DataBlock. This will cause syntax errors and ultimately, a lot of extra work on your end to find every occurrence and change the name manually. Better to add a meaningful name as soon as you create the variable or parameter, so that as you continue building, your design will reflect the correct variable names.

Worrying about such a small detail may still seem like a waste of precious time, but which of these lists would you rather work with:

Naming-Conventions_list-graphic

The list above is fairly small, so it may not seem like much. However, as you begin to get into more complex DataBlocks, multi-form dashboards or detailed banded reports, naming conventions take on a whole new appeal. Take this for an example: I recently completed a banded report that has over 100 expressions, labels, variables, bands and other objects. If I have an element called ‘Expression27’ what does that tell me? Not much. Now, if I’d named it ‘HB3_EXP_ResetBudgetSubtotal’ instead, that’s a different story. ‘HB3’ tells me that it’s on the third Hidden Band of my report, ‘EXP’ tells me it’s an expression, and ‘ResetBudgetSubtotal’ describes its function. The [location]_[type]_[purpose] formula is fairly easy to follow, and you can always tailor it to your needs. (Check out these lists of useful abbreviations – one for DataBlock Designers and one for Report Writers.)

Although this little step may slow you down a bit in the beginning of the development process, in the long run, you will be glad you took the time to use a good naming convention. In future blog posts, I will give you some tricks on how to speed things up, to make up for any lost time spent on naming!

Like this blog?

You might also like this On Demand webinar:

Vicki Wayne is the Head of Client Success at Evisions. She has been in the higher education industry since 1998, gaining experience in both public and private institutions along her way to joining Evisions in 2012. Vicki is a certified Project Management Professional and has extensive functional and IT knowledge. She graduated from Purdue University in 2002 with a Bachelors of Management Information Systems, and in 2006, she received her master’s degree in Information Systems Management from Keller Graduate School.

Related Posts

Evisions CO-OP: Top 10 Most Viewed Argos DataBlocks

Evisions CO-OP: Top 10 Most Viewed Argos DataBlocks

The Evisions CO-OP User Community is a collaborative place where clients can share ideas, experiences, development, forms, DataBlocks, and reports with their peers. To give you an idea of what fellow Argos users are doing and looking at, we present the Top 10 Most...

Navigating the Evisions Customer Community

Navigating the Evisions Customer Community

The Evisions Customer Community has always been an invaluable tool for clients. It serves as a resource for peers in higher ed to share knowledge and find answers. On May 7, 2019, a new community portal was launched. Why? Because we listened when our clients told us...

Shining the Light on SQL Variables in Argos

Shining the Light on SQL Variables in Argos

When an institution begins its reporting efforts – let’s say after recently changing databases or reporting tools – one of the first steps usually taken is to replicate what they had before. Often, this means creating some type of file and distributing it to users....

5 Comments

5 Comments

  1. Cavin Deiterich

    When I have a datablock with multiple forms I use a suffix, _F0…_Fn, so I know which form the parameter is on. I prefix my form name with the same prefix F0_ … Fn_. This keeps them sorted in form order. As an example, a term code drop-down on the first form would be parm_DD_SelTerm_F0. The form name might be F0_TermStats.

    Reply
  2. Calvin Deiterich

    I use the following naming convention. The form is prefixed with F0_ … Fn_ . The parameters on those forms are suffixed with _F0 … _Fn. As an example, if the first form is titled Term_Stats and it contains a term code drop-down, the form name would be F0_Term_Stats and the parameter would be parm_DD_SelTermCode_F0. Using this method, all the term code parameters are grouped together, as well as sql_, etc. I also see the advantage of prefixing the parameters with the form designation which would keep all the parameters, etc. grouped by form.

    Reply
  3. Dane Frazier

    I too use similar naming conventions:

    We do a lot of multi-form datablocks.

    Tracking 30+ variable elements gets nutzy… so :

    form: frmMain, frmBlah, frmBeep, frmBuzz

    gui elements: dd -> drop down; lb -> list box; ck -> checkbox; mc -> multi-column, etc.

    forms are named ‘commonly’ for their use: frmMain, frmEnrlOlap, frmPirateData, etc.

    parameters become:
    parm_frmMain_lb_term

    results (such like that come from an on-screen multi-column or olap:
    res_frmBuzz_mc_allEnrolled
    res_frmBleep_olap_enrPctTarget

    sql variables become:
    sql_FERPA (an anon. pl/sql block for tracking the basics of a FERPA audit requirement)
    sql_frmBeep_chrtEnrl (an SQL variable to drive an enrollment chart on form Beep … etc)
    and so on.

    Also, we use form notes to track:
    note1: datablock owner,
    note2: datablock stakeholders
    note3: service ticket URLs for tickets related to this datablock
    note4: code driving ticket added to GIT repo so we have a pure driving SQL and parms backup in text format (from a text based template we came up with)

    We use the Description to highlight the multi-form datablock functionality:
    datablock “Student_Reports” description example:

    Datablock contains “Sub Reports”
    ———————————
    Report QuickViews:
    ———————————
    Find Active Courses
    Find Active/Current Students
    Find Alumni
    Find Departed Students
    Find Housing Contact Details
    Find Sponsored Students
    Find Students Applied
    Find Students By Course
    Find Students in a Course Not in Other Course / no core courses
    Find Students with Holds
    Find Students with Perfect Attendance
    Find Students with Perfect Grades
    Find Students with Perfect Attendance & Grades
    Find Students Registered not in ALCI Courses

    Reply
  4. Vicki Wayne

    Dane –
    Thanks for the suggestions – really good ideas! I know we don’t always follow a standard with ‘general’ SQL variables that aren’t related to a particular form. The addition of parm & res does a nice job of grouping things together in the variable pane as well!

    I always stress in my presentations and training that the Description and Notes sections are your best friend!! They come in VERY handy – especially when users are trying to search for specific fields/reports. The Object Contents search in Argos is a handy, little known trick to locating objects within forms and reports! By including lots of detail in your descriptions, you are creating metadata for the search to look through! Great job!!
    Vicki

    Reply

Trackbacks/Pingbacks

  1. Best Practices for Banded Report Design | Evisions - […] can’t stress this point enough: a good naming convention is a lifesaver, both for yourself and for anyone who comes after…

Submit a Comment

Your email address will not be published. Required fields are marked *

Share This
X