Channels ▼

Bil Lewis

Dr. Dobb's Bloggers

What is in a name?

April 28, 2008

That which we call a rose, by any other name would smell as sweet.

Will Shakespeare. How I love that guy! I went to the Boston Public Library's reading of all 154 sonnets a couple years back. I got #109, which I just happened to know by heart. Yeah, poetry is beautiful.

Computer programs, on the other hand are not beautiful. Not in that sense.

Computer programs intended to be functional, and what beauty you might ascribe to them relates to that, rather than a luxiorious flow of metaphorically related concepts.

And how I choose to name my elements is as functionally descriptive as possible, at all expense to beauty. My names are boringly repeatitive and unimaginative. They lend no artistic note to my programs what-so-ever. They do, however, describe as accurately as possible what they are intended for and that's what's important.

My mantra to my students (oft repeated to myself) is:

Good Code is Readable Code.

Nothing else is half as important.

If you hand me a program that's slow, but readable, I will be able to improve its performance. If it's buggy, I will be able to find those bugs. If it needs new features, I will be able to add those features.

But if the code is unreadable, I'll be hard pressed to do any of those and will eventually be forced to drop the entire code base and start over again.

I always show bits of students' code in class and ask the students to comment. Are the names descriptive? Are the comments sufficent? Are they useful or do they just get in the way? Do methods fit neatly on a single display or do I have to scroll around to read them?

These are important issues!

I now work on a big genomics project that mixes Python, Java, and Tapestry. The interfaces between the languages are very robust, but still the source of a plethora of bugs. In Java we use a generic pipeline that passes arbitrary objects from step to step, exacerbating the problem. Our code looks like this:

{geshibot}public void processObject(Object obj) {
Object[] objs = (Object[]) obj;
Sequence target = (Sequence) objs[0];
String filepath = (String) objs[1];

Sequence match = process(target, filepath);
callback.call(new Object[] {target, match});
}{/geshibot}

where the callback eventually calls the next step in the pipeline. It works quite well, except that we're passing all these strange objects down the pipeline and we're constantly doing blind casts, hoping that the preceeding step didn't accidently pass the wrong type of object. (It is so nice to have a compiler that will check those things for you!)

In these cases it becomes imperative to use an insanely strict naming scheme. As above, we do a lot of work with Sequence objects. These objects contain strings which are the actual sequence of neucleotides in the DNA. In much of our older code, you can see things like this:

{geshibot}Sequence complement(Sequence sequence){
String seq = sequence.getSequence();
String reverse = complement(seq);
Sequence revSeq = new Sequence(reverse);
return revSeq;
}

String complement(String sequence) {
StringBuilder rev = new StringBuilder();
for (...) {...}
return rev.toString();
}{/geshibot}

And when we start passing around a couple different Sequence objects along with their respective String representations and adding them to arrays of {moscode}Object[], {/moscode}it gets confusing very quickly. And we have lots of these.

Consider the lowly file. Should a variable called "filename" include the directory path or not? Is it OK if it changes?

{geshibot}String read(String filename) {
if (! filename.startsWith("/"))
filename = directory + filename;
File f = new File(filename);
...
}{/geshibot}

My answer is of course "No". Whoever calls {moscode}read(){/moscode} knows if it has just a name and extension, or if it has the entire path. It should call the appropriate method:

{geshibot}String read(String filepath) {
File f = new File(filepath);
...
}

String readFromDirectory(String filename) {
String filepath = directory + filename;
return read(filepath);
}{/geshibot}

And I never, ever put different information into the same variable, ala

filename = directory + filename;

There lies madness.

For smaller projects, this isn't such a big deal. But as the project gets larger, it becomes more and more important to be clear and consistant.

IMHO

Related Reading


More Insights






Currently we allow the following HTML tags in comments:

Single tags

These tags can be used alone and don't need an ending tag.

<br> Defines a single line break

<hr> Defines a horizontal line

Matching tags

These require an ending tag - e.g. <i>italic text</i>

<a> Defines an anchor

<b> Defines bold text

<big> Defines big text

<blockquote> Defines a long quotation

<caption> Defines a table caption

<cite> Defines a citation

<code> Defines computer code text

<em> Defines emphasized text

<fieldset> Defines a border around elements in a form

<h1> This is heading 1

<h2> This is heading 2

<h3> This is heading 3

<h4> This is heading 4

<h5> This is heading 5

<h6> This is heading 6

<i> Defines italic text

<p> Defines a paragraph

<pre> Defines preformatted text

<q> Defines a short quotation

<samp> Defines sample computer code text

<small> Defines small text

<span> Defines a section in a document

<s> Defines strikethrough text

<strike> Defines strikethrough text

<strong> Defines strong text

<sub> Defines subscripted text

<sup> Defines superscripted text

<u> Defines underlined text

Dr. Dobb's encourages readers to engage in spirited, healthy debate, including taking us to task. However, Dr. Dobb's moderates all comments posted to our site, and reserves the right to modify or remove any content that it determines to be derogatory, offensive, inflammatory, vulgar, irrelevant/off-topic, racist or obvious marketing or spam. Dr. Dobb's further reserves the right to disable the profile of any commenter participating in said activities.

 
Disqus Tips To upload an avatar photo, first complete your Disqus profile. | View the list of supported HTML tags you can use to style comments. | Please read our commenting policy.
 


Video