Why you need linguistic skills – part 1

February 8, 2008 By

Language in dictionary by Christian Grass @iStockphoto

While writing code may seem very logic-based and technical in nature, your skill in human languages is equally important. Why else would Visual Basic read like English? In this series of articles, I’m going to talk about why improving your linguistic skills make you a better programmer.

Broaden your mind

A limited range of vocabulary restricts your imagination. Part of imagination requires you to describe something. The more words you can use for describing, the more vivid, the more exact and the more complete the object of description becomes.

As a programmer, you have to translate business logic, task requirements and given instructions into code. The better your grasp of language, the better you’re able to imagine the final product, and thus the better you’ll be able to visualise the code and write it. What it comes down to is you must understand something that someone else wrote. You need to know the nuances of your language of choice because that someone may have wanted one thing, but actually wrote something else.

For example, in one of my user task requests, there was this requirement about entering random input. Based on the business context and the web form that was to support this feature, I deciphered it as being able to enter any range and any number of input in a specific format. I checked with the user, and it was indeed that way. Sometimes users lie, unwittingly perhaps, and in this case, using the wrong words to describe what he wanted.

Give it a name

What’s the one thing you do every time you code that requires linguistic skills? Name your variables. Every time you declare a variable, you make a conscious choice on what that variable’s fate in the ensuing code is. Every time you name a variable, you make a conscious choice on what is required of the variable.

There’s a concept I read in a fantasy story by David Eddings, and it goes like

Know the name of an object, and you gain power over the object

Yet some programmers are lousy at naming variables. Some programmers don’t care about the variable names. I bet some programmers even hate naming variables. Why else would there be names such as “a”, “b”, “c”, “DataGrid1″, “DataGrid2″ and “Table1″?

Of course, there are perfectly rational decisions on using certain names. Variables in loops are usually single letters, and they are usually “i”, “j” and “k”. That’s probably a 3-level nested for loop in the making. I’ve gone up to “l”, “m” and even “n” before (matrix manipulations. Fun).

Based on context, you can easily know what those loop variables are used for. And that’s the important point, the context in which a variable is used. A simple “dt” for manipulating dates and times in a small and well-defined section of code is ok. But if there’s no context, can you tell what the variable is used for?

“It’s compiled into an executable anyway. Besides, there’s the search function,” you say.

Of course, tools such as Lutz Roeder’s Reflector make it easy to obtain code. You can use the search function to find where a variable is used and thus gain an understanding of its purpose. “t1″s and “t2″s don’t bother you at all.

Writing code is in the same spirit as writing a sestina, or writing a letter, or writing a business document. You are writing to be understood. And until artificial intelligence improves, you’re writing to be understood by a human.

The compiler might understand what you wrote (or not, depending on how bad a programmer you are). But you’re really writing for a human being. Someone is going to use that application you wrote, and they’d better know what it does. Someone is going to maintain your code, and they’d better understand what it does.

I can understand the difficulty faced by my Chinese reports (stationed in China), whom I pass some programming tasks. English isn’t their native tongue. The specification documents need to be written in easy, simple language for them to understand the business logic. Before any French or German programmers hammer me with protests, I want to point out the importance of the language used in the communication. Again, it’s about context. If your users use English and your documents are in English, your code had better be easily read in English.

Obfuscated code is hard to read because the context is taken out, be it requirements, indentation, spacing or addition of superfluous stuff. To add and support context around code, you need a certain level of linguistic proficiency (yes, basic spelling and grammar counts).

So my conclusion with bad variable names is that they arise out of a combination of:

  • Limited vocabulary range
  • Lack of imagination
  • Plain laziness

What’s your excuse for bad variable naming?

Filed Under: Programming Tagged With: , ,

Design analysis paralysis

February 6, 2008 By

It was the start of (yet) another project. The requirements were in. The database table design was done, subject to changes if the final code needed it.

So I sat, arms on the arm rests, slumped slightly in my comfy chair. Leaning slightly backwards, I had my eyes on the ceiling, looking for inspiration, gently rocking on the chair. Shapes and colours formed and dissipated, words and numbers just barely clear enough to see.

I was visualising my user interface design.

After I had the general idea that the imagined web application user interface, required business logic and database tables were going to match, I started drawing. I pulled a few blank pieces of paper from my stash of trash paper, and drew an outline of how it would look on the web form. Panels, textboxes and dropdownlists. Datagrids, buttons, checkboxes and radio buttons.

Should the textbox take in only input of “dd/MM/yyyy” format? Restrict only numeric input? I scribbled my notes beside the interface controls on the paper.

Finally, I’m done. I’ve got arrows denoting process flow with notes on input and display output. Then I went back and thought again. Would this interface design work? Could it fulfil the business requirements? Could it support insert, update and delete operations to the database tables?

After half an hour, something inside of me screamed, “Stop this!” I’m in design analysis paralysis. I heaved myself out of my reverie, and started actually coding.

Has this happened to you before? You want to make something perfect, so you think about the design, planning it this way and that. You chew over some of the decisions, “oh that’s not gonna work well”, and rearrange some parts.

There comes a time where no more designing can help you. The only way to see if your design works is to actually start writing some code. With working code, you can test. With tests, you get feedback, with which you can correct your code.

Let me give a non-programming example, my writing of a sestina (of the poem category). Its rules are simple. There are 6 stanzas (or paragraphs), each stanza consists of 6 lines. Each of those lines must end with a word from a group of 6 words. Every stanza must have lines ending with one of those words. The words must not repeat within a stanza and they must be in a certain order. The seventh and last stanza has only 3 lines, but each line must have 2 of those special words, and one of the words must end each line. I probably confused you more than explained how a sestina works, so you might want to read it up yourself.

So what I did was come up with the 6 words first. Analysing the sestina requirements, the obvious observation was that every one of those words would be used 7 times (7 stanzas). Instinctively, I knew I needed words preferably with more than one meaning, so I don’t keep repeating the same theme.

Then I realised that if the words could be both a noun and a verb, then it’s easy to describe it with more than one meaning. So “code” can be programming code, or cryptographic code, or code as in writing code. I was stuck in a mental quagmire coming up with those 6 words, trawling through my vocabulary for words with ambiguous meanings and double entendres.

Obsessed with fitting the words, a theme and sestina rules, I got that “Stop it!” scream again. I needed to just start writing the sestina. I needed to stop designing in my mind, and start doing something.

So on my computer, I just typed out the 6 words first, one on each line.

sun
code
water
tree
two
force

Then slowly, I filled in the details,

Just like the life giving warmth of the sun
You can create a better world through your code
Even something as simple and mundane as water
This element of old courses the veins of a tree
With earth and air, ancient elements the other two
They fuse together, becoming a beautiful force

Each line gives inspiration for the next. Then I typed out the 6 words for the next stanza in the order required.

force
sun
two
code
tree
water

And I filled that as well. Some stanzas I had a theme to work with, and the words seemingly flow and automatically end with those words I chose. Some lines required a bit of nudging here and there. Some lines required changes so the whole sestina still reads smoothly.

Then it’s done. I proofread it, checked the visual look on screen and recited it for cadence testing. And it’s done. If I had still been stuck deliberating over my choice of words, I’d never be able to get anything done.

The only way I could move forward was to break out of design mode and do something. So how do you break out of design analysis paralysis? Have you ever been in one?

[To the Chinese readers out there, have a happy Chinese New Year (7 Feb)! Check out some of the decorations in my office.]

Filed Under: Programming Tagged With: ,

Fear of the security panel

February 4, 2008 By

Digital access by Eva Serrabassa @iStockphoto

Software security is a big thing. You have to be aware of it from day one, and your code must be designed with security in mind. There are no coding details here. Instead, you are going to learn the mentality behind coding for security, and a lesson in human behaviour. And it starts with a story…

The ride up

It’s a typical morning to work. I arrived at the office lobby at 2nd floor. The 1st floor is actually the car park. We can discuss this architectural mystery some other time.

Sometimes, I’m alone, which was cool, because that meant I could take the lift all the way up to the 6th floor where I work. Otherwise, there would be people exiting at the 3rd, and the 4th, and the 5th, and ooohhh, finally, my floor.

Now there are 2 lifts. I timed it, and my experiments told me that squeezing into the 1st available lift to go up to the 6th floor where everyone was in, was slower than taking the next lift that I could take all the way up.

Anyway, on the rare occasion where I find myself caught in a full elevator, I noticed a peculiar behaviour. Now I’m not saying everyone’s like this. It’s just something that’s frequent enough that I took note of it.

First, I need you to visualise the inside of the lift. The doors, which open and close on both sides of the lift, is in the centre of the lift entrance. To either side of the lift are the lift floor buttons. Every single floor has its button, plus the obligatory open, close and “come help save me” alarm buttons.

“Tell me about the weird behaviour already!” you exclaim. Ok, ok…

Some people would stroll straight to the back of the lift, even though they’re the first in. I mean the nice thing to do would be to go to the button panel and hold the lift open while the rest of us are trooping in, right?

Now here’s the even more peculiar behaviour. Some people, even though they’re right next to the button panel, don’t lift their finger to hold the door open at all. Sure, there’s another person at the other panel too. Then that person exits the lift at 3rd floor. No finger lifting. And while people are exiting too, the lift doors close. I had to rush in and take over at the button panel in one instance.

The long walk to the security panel

There’s a reason why I just used a couple of hundred words describing my lift ride. Those very people who don’t lift their fingers to help hold the doors open? On the 6th floor, suddenly, they’re filled with gentlemanly virtue or immense courtesy, and their fingers flew up to press the “open” button. Why?

So that they weren’t the first ones out. Which meant they wouldn’t be the first one to reach the security panel. Which meant they wouldn’t have to whip out their security passes and authenticate themselves, and get the office doors open, and heaven forbid, let the rest of us in as well.

Let me give you a floor plan of the journey from the lift to the office security panel.
Office entrance

These people would hold the doors open and let everyone out of the lift. They’d stroll normally at the same (or preferably slower) speed than the other people. Someone had to open the office doors. This way, they’re the least likely to have to authenticate themselves.

I believe they are legitimate staff working in the office. I believe they have legitimate security passes for authentication. I also believe they’re basically nice people. So why do they behave in such a manner? My conclusion is that they’re plain lazy.

The authentication process is really quite simple. Sure, the security panel can be faulty, and the security pass doesn’t work sometimes. We have this ongoing joke where if your security pass doesn’t work, the company probably fired you. *smile*

But is taking out the security pass for authentication that bothersome?

“What if those people aren’t at the lift button panels?” you ask. “What if they’re stuck at the front of the lift? What then?”.

Aha, here’s the really ingenious part. Please refer to the office floor plan above. See that visitor couch to the left? They would stroll, ever so slowly towards the visitor couch (or the fire escape), letting whoever was behind them to overtake them and thus reach the security panel first.

And after someone else authenticated successfully, and the doors were unlocked, what do they do? They just waited for the authenticator to open the doors as well. During the authentication process, these ingrates couldn’t go to the doors and open them the moment it’s unlocked. They needed someone to authenticate, unlock the doors and open the doors for them too.

Conclusion

Most of the people working on my floor are developers. Except for the administrative staff (only 2), and the team leaders and managers, the rest are all working directly in software related roles. Programmers, systems analysts, consultants.

If these people can’t even be bothered to authenticate themselves at the office doors, what are they doing about software security in the programs they write? Do they implement security or do they just talk about it?

Filed Under: Work Stuff Tagged With:

Too much flexibility can hurt

February 1, 2008 By

Bendy giraffe by Chris Crafter @iStockphoto

I’ve learnt the hard way that sometimes, designing and coding an application to handle every single kind of scenario is painful. It hurts to maintain and it hurts when it comes time to grow. Flexibility is overrated.

With experience, comes wisdom. I learnt to set limits on what an application can do while still adhering to requirements. It’s when I didn’t assert my programming expertise to inject doses of practicality into users (and their customers) that I run into trouble.

Unbounded flexible requirements

It used to be an Excel spreadsheet macro-run calculation. It was simple and effective. Right till the point where the user had to manage many customers (which was a good thing). Then he had to deal with some non-standard calculations from the customers that’s hard to use macros to run (which was not so good).

So he came to my (ex) manager and wanted a system, an application to help grow and sustain this business. Parameters to the calculation algorithm were discussed. Business logic were added. Reports were needed. Database tables with master and detail relations had to maintained. User groups, profiles, access rights.

It just grew and grew.

Then the customers started pushing their way. They wanted a more customised agreement with the user, which resulted in more customised solutions and parameters to the existing agreements.

So my manager and my colleague discussed at length and cracked their brains for a generic application solution. It had to include the customised parameters and still work for every single existing customer agreement. After much head-cracking, a flexible and generic solution was found.

Then the data source files were modified. Had to change a little. The accounting system required something from the application. Had to change a little. The tax in Singapore changed from 3% to 5%. Had to change a little. The tax will probably change, so made sure future tax changes were catered for. Cracked brain a bit more. The customers wanted something more. Had to change a little.

Granted, some of the changes were forced upon us, and the application had to adapt. What about the changes where there was some control? What if the user had been a bit more adamant about the agreements, to simplify his relations with all his customers by having set conditions and parameters in his contracts?

Sure, he might lose some business. Yet his existing customer contractual agreements would be easily understood. Right now, some of his contracts contain wildly different calculation logic than some others. And the application had to cater to every single one of those logic conditions.

And it’s hard. It’s like trying to find the ultimate single explanation that unifies all the four fundamental forces. There is that distinct possibility that there might not be one.

Unbounded limits of depth

I was once asked for advice on another team’s project, which involved some storing of user and departmental data. They were doing some feasibility analysis, and there’s this requirement that theoretically, data about users could be stored to infinite levels of depth.

For example, a clerk could be reporting to a supervisor, who’s reporting to a manager, who’s reporting to a senior manager, who’s reporting to a director and so on. The users of that team wanted the flexibility to dynamically change user group relations and store many levels of users, as in unlimited.

Very few things stretch to infinity and still work practically. When credit card companies say you have unlimited credit, what they meant was that you have a very very large credit limit. When web host companies say you have unlimited storage space, what they meant was that you have a very very large amount of bytes to play with.

The word “unlimited” refers to the fact that you are very highly unlikely to ever reach the maximum limit imposed. There’s still a limit. It’s just that you are very highly unlikely to ever reach it. Get the drift?

So back to the project. What the users want was not unlimited levels of depth. What they want is the flexibility to go up to any number of depth levels. So I asked the team members, “What is the highest number of levels the data can go up to?”

5. Maybe. So I told them to just write their application based on a maximum depth level of 8. Their users would probably never hit this limit. Even if they did hit the limit, the code should have been written such that it’s easy to extend anyway, so it’s not a problem.

But what about game modding?

That’s slightly different. I’ve been talking about logic flexibility, the ability to change the rules of the program in a dynamic way. Game modding involves data flexibility.

Game programmers still write code based on specific rules and logic. But they allow their code to work with a large variety of data, thus increasing the flexibility of the code. This is one of the ways computer games extend their lifespan.

For example, The Sims have set rules on the behavioural simulation of virtual people. Yet by allowing user generated content, such as custom furniture, hairstyles, clothes, players have much more varied experiences. The rules and logic didn’t change. The data did.

Closing

In short, design your application to be more generic than the requirements you receive. This allows some room for changes and improvements with little code change. However, you don’t have to cater for the largest possible set of scenarios that can possibly happen.

Know when to stop expanding your code’s limits.

Filed Under: Programming Tagged With: , ,
Newer Posts »