rebugged <insert pompous tag line here>

Disclaimer (2017): This post was written a few years ago when I was relatively new to programming, so take with a grain of salt.

12 valuable lessons I learned from my two years experience as a developer. Some are bits I picked up along the way, but some are hard learned tidbits of wisdom I learned from my own mistakes.

The 12 points discussed in the post are the following:-

1. Know your tools
2. Modularize
3. Error messages are your friends
4. Plan, Plan, Plan
5. Maintain predictability in code
6. Write beautiful code
7. Refactor
8. Central location for configuration/settings
9. Push towards automation
10. Keep the comments updated
11. Write jokes in comments
12. Choose the right team

 

1. Know your tools

Programming is no longer just typing code out of the air into your text editor and compiling it after you are done. Programming is more of an interactive process now.

Lots of tools are available now, that can boost developer efficiency. Most programming languages have rich IDE’s with features such as “intellisense”, auto-complete, realtime syntax checking, profiling and debugging assistance, source control integration etc built-in. Knowing these various tools and features are not a must to be a great programmer, but, without a question, better tools can boost your efficiency as one.

There are programmers who swear on their text editors.

When I started out as a programmer, I didn’t know that you could trace (execute) your Javascript code line by line and watch the values of variables in realtime, as they change.

I found it accidentally one day. And I still remember that moment. It felt like pausing time. I felt like I was using magic sands to stop time. (When you play the game, Prince of Persia you can pause time using these magic sands. When you do this in the game, everything except you are frozen in time, and when everything including your enemies are frozen, you can go around killing your enemies and doing stuff.)

It was amazing! Anyway, what I was telling was that, if you find out and utilize such features and tools, you will find life much more easier. Learning little tricks like these are like collecting those magic mushrooms in Super Mario. They give you super powers, and hopefully, you will be able to knock down your enemies more easily.

“If I had eight hours to chop down a tree, I’d spend six hours sharpening my axe” – Abraham Lincoln.

So, get sharpening your axe!

 

2. Modularize

All software projects start small and gradually grow over time, adding features and getting fat. So when you start planning a project, modularize it – divide it into modules.

A module can be a section doing a particular task. Or a module can be a semantic group of functionalities. For instance, if you were making a program like Micosoft Word, then you can put together all the code for text formatting (coloring text, making it bold, italics, changing font etc) together into a single module.

Such breaking up of a project will make assessment, assignment, development, management and maintenance easier.

An important thing to note about when you modularize your project/program is that, modules should be be as independent as possible. In computing, this design principle is known as Separation of Concerns. Later, the different modules can be plugged together to achieve the full program.

Also, make sure your modules make sense in a semantic and/or functional way. You can have sub-modules and sub-sub modules inside your module.

 

3. Error messages are your friends

Error messages thrown by the programming language or its environment are immense help in identifying and solving issues.

Consider a Javascript program with just 100 lines of code. You, the programmer mistyped a variable. Say this variable was being used only in a special case. As a result, the program is not working as intended in the special case. If an error console is not present and you don’t see an error report, you are very unlikely to even find out that there is an issue.

So when you develop/debug/test, always enable error reporting. Error reports usually have all the information you need to fix most of the issues, down tho the line number where the problem is.

All languages (that I have ever encountered so far) have one way or another to report issues. If it is browser-side Javascript code, check the error console of Firebug or Webkit’s Inspector. If it is a PHP program, make sure error reporting is enabled for E_ALL and monitored.

If you are working with PHP, here is a nice article to help you tailor error reports the way you want. So make sure you learn more about error reporting for your particular programing environment.

 

4. Plan, Plan, Plan

“Weeks of programming can save you hours of planning” – Author unknown.

When I first learned programming (C language) in college, whenever a programming question was given to me, I would start up my IDE (Turbo C) and start typing #include<stdio.h> void main() ….  etc. I would just type furiously, until I get blocked. Then only I would start to think where I’m going next.

Well, actually, this approach worked for me, in college. I would like to quite humbly 😛 let you know that in our batch, I was the first one to compete the programming task and exit the lab on our C programming lab examination. (Its my blog, I’ll brag 😉 )

The thing is, proceeding without planning will work when you are writing a program in school to check if a string is a palindrome or not. But the case is very very different when you are building a large application for real-world use. Without proper planning, you will overlook issues, write crappy code and waste time and resources. Let alone the later feeling of self pity.

Let me tell you what happened to us in one project. In this lame social network application that we were making, the site’s users were able to message each other, naturally. When user A sends user B a message, we inserted one row in the messages table with from=A, to=B. User A could see this message in his ‘Sent messages‘, and user B could see this message in his ‘Inbox‘. Everything worked quite well – until user B decided to delete the message from his damn Inbox. Well, when B deleted the message from his Inbox, bam!, the message was deleted from user A’s ‘Sent messages‘ also.

The problem was that, each message was a saved as a single record in the messages table, and actions from both sender and recipient were directly applied to it. So if either its sender or recipient deleted it from his mailbox, it would disappear from the other person’s mailbox too. Oh, and let me regretfully confess that I was was the one designed the above said database. All because I jumped in without planning properly. Well, there is a lesson learned, and a couple of sleepless nights 🙂

Anyway, what I do now is that, when I get a problem, I analyze and understand it well. Then I outline a plan to tackle the issue. Once I’ve outlined the solution/algorithm I’ll try to see if there is anything I overlooked. Once I’m happy with my plan, I’ll go ahead and implement it. If the problem is complex, I’ll ask somebody to take a moment and review my plan.

As humans, we are prejudiced about things based on our very limited knowledge. As a programmer, it is always good to ask your friends or ask in StackOverflow or somewhere to see if anyone else has a different solution for the same problem.

 

5. Maintain predictability in code

When you are working in a project with more than one developer, discuss with your team and decide upon the conventions you will be using. Conventions include, but not limited to, naming of variables, classes, functions, database tables etc, interfaces of modules, coding style, documentation practices etc.

When commonly agreed upon conventions are used in a project, it gives the advantage of predictability to the programmers. Predictability probably sounds unimportant, but believe me, it is important.

For example, in a project, we agreed that entity classes will be the singular form of the entity name in UpperCamelCase. We also agreed that all tables will have a method such as get_entity_details(entity_id) to get a particular entity’s details. So naturally a person can expect that User->get_user_details($user_id) will give a particular user’s details, without checking the code or documentation. Do you see the beauty of predictability? May be you don’t yet. But take this, such perks are huge bonuses when working in big projects.

And a little rant, I once worked with a programmer who made frequent careless spelling mistakes. In code. If he was creating a User class, he would probably write a misspelled member function like this get_uesr_details(). When someone else tries to call the function in their code, they will, out of instinct, use the correct spelling, which is get_user_details(). Of course it will trigger an error somewhere saying that “function get_user_details() does not exist”, and the second programmer will have to refer the my dear buddy’s code/documentation to see what the wonderfuck is going on.

Man, did that guy give me enough headaches for a lifetime or what!

Checkout the coding conventions for PHP, by the Zend Framework people. Even if you are not working with PHP, you can get some ideas from it.

 

6. Write beautiful code

“Programs must be written for people to read, and only incidentally for machines to execute.” – Abelson / Sussman

When you write a piece of code, keep in mind that it is very very likely that you or someone else will be coming back to the code in some point in the future. May be someone will want to modify the code and add a new feature, or may be someone will need to fix an issue in it or may be someone just need to look at your code and study it. If you write clear, readable code, your colleagues will hate you less for it. And there is a good chance that you will go to programmer heaven when you expire 🙂

There was this buddy of mine who never ever use consistent indentation. I have a screenshot of his code below.

If it missed you, indentation, brace positions and everything else is inconsistent in those 6 lines given above.  The above code might still seem ok for some of you. But a real program is almost never 5-6 lines like this. Imagine a source file with 2000 lines of code like this, where complex logics are implemented.

Jeff Atwood in this essay says that “beauty isn’t just skin deep, so beauty of a piece of code lies in the underlying ideas and algorithms represented there, not just in the code itself”. He’s right, but it doesn’t hurt if the code itself is beautiful and readable, does it?

Here are some pointers to write beautiful code:-

1. Consistency is a key factor in writing elegant code. Decide on a style and follow it.
2. Proper & consistent use of white space (indentations, space between tokens etc)
3. Proper use of comments.
4. Stick to conventions.
5. Meaningful names for variables, methods, classes, tables, files etc.

These are a few points that just came of the top of my head. Here is a well written article with guidelines on writing beautiful code.

 

7. Refactor

Refactoring is making slight changes in the existing code to improve it. Continuous improvements will make the code more understandable and maintainable.

“By continuously improving the design of code, we make it easier and easier to work with. This is in sharp contrast to what typically happens: little refactoring and a great deal of attention paid to expediently adding new features. If you get into the hygienic habit of refactoring continuously, you’ll find that it is easier to extend and maintain code.”
– Joshua Kerievsky, Refactoring to Patterns (From Wikipedia)

But at times, you will face situations where just refactoring isn’t enough. At those times, a complete rewrite could be the only solution. Joel Spolski, CEO of StackOverflow and the renowned author of Joel on Software, writes in an article named Things You Should Never Do, Part I, that one should never rewrite code. He reasons that the project will be set back in its schedule if gone for a rewrite. Ok, never rewrite is a little too strong a choice of words here, imo. So, lets take home this:- 1) refactor continuously, 2) rewrite only when there is no other option.

 

8. Central location for configuration/settings

In typical PHP projects, there is a file called config.php, which holds the configuration settings. I’ve seen projects in other languages also employing similar configuration files. It is always a wise choice to store all your configuration settings grouped together in a central location.

This is helpful in deployment, because there are fewer files to edit and configure. Also, it is hard to miss one of the settings when you are grouping them together.

The optimal scenario is to save configuration in a separate dedicated file which is exclusively for saving configuration. It is best if you could avoid adding application or business logic into these configuration files. When Version Control Systems (VCS) are used for managing the source code, we will usually need to keep the configuration files outside of source control’s tracking. If you had other code or logic also included in your configuration files, excluding these files from source control will be messy.

 

9. Push towards automation

Lots of things at different stages in a project can be automated. The most commonly seen automation scenario was automation of test case verification. Deployment automation is also on the rise now. Previously shell scripts and similar techniques were used for automated deployment.

Now there are tools such as Capistrano for deploying web applications which allow sophisticated level of control with ease than the shell scripts.

In a project I did, we wrote a script to sweep over the United States to pick up business listings and save them to a database. The script took around one week to complete one full scan over the U.S. When one sweep was over, we had to manually reset the script with new start points (latitude and longitude) for the script to start again. This was ok initially, because we had to do it only once a week. But later we were running multiple script instances at the same time from multiple servers to speed up our gathering of data. So we had to manually reset the completed scripts more often, usually once every day, which soon enough became very cumbersome. It was an unnecessary process that wasted several of our precious man-hours.

Later we automated the script-reset process and things were swift.

Quora Engineer, Edmond Lau in his insightful answer to “What makes a good engineering culture?” says:-

In his tech talk “Scaling Instagram”, Instagram co-founder Mike Krieger cited “optimize for minimal operational burden” as a key lesson his 13-person team learned in scaling the product to tens of millions of users. As a product grows, so does the operational burden per engineer, as measured by the ratio of users to engineers or of features to engineers.  Facebook, for example, is well-known for touting scaling metrics like supporting over 1 million users per engineer.

When repetitive tasks are automated, we are making the system take care of itself with least manual interference. Edmond Lau continues to say that automated tasks must be logged and measured:-

Without monitoring and logs to know what, how, or why something is going wrong, automation is difficult. A good follow-up motto would be to “measure anything, measure everything, and automate as much as possible.”

 

10. Keep the comments updated

“It is better to have no information rather than having wrong information“. When I ask someone for route, I would rather have them say “I don’t know” than pointing me in the wrong direction.

Comments are like signboards. Comments, when properly written, are as good an asset as the code itself. They will help the reader get a grasp on what is going on in the code faster.

Now imagine the case where this nice programmer wrote a well commented program. Anther guy, when modified the program didn’t bother to update the comments to reflect the new modifications he made. Now the program has comments that are no more valid. Now the program is going in one direction, but the comments are pointing the other way. Well, what more can be said. The third person trying to understand the code is in for a serious brainfuck.

Don’t ignore comments and leave them wrong because they do not affect the program’s working. A program is already difficult to read than it is to write it. So, keep your comments updated and accurate.

 

11. Write jokes in comments

/*
* After 36 hours, 2 holes in my wall and writing my code right beside the API
* this still doesn't work.
* function getMap():void takes in an event object @param: evt:mouseEvent
* I will now retire for the day with a bottle of rum and 2 hours of crying
*/

Another one:-
// I dedicate all this code, all my work, to my wife, Darlene, who will
// have to support me and our three children and the dog once it gets
// released into the public.
If you can light up a moment of another miserable programmer treading through your code, please do it 🙂

The best thing about writing jokes in comments is that, your joke doesn’t even have to be explicitly funny or witty. Almost anything light hearted or foolish you write there will seem funny to someone.
// If this code works, it was written by Paul DiLascia. If not, I don't know
// who wrote it
(Comments collected from StackOverflow)

 

12. Choose the right team

Last, but not the least, choose the right team. This applies especially if you are a team lead or something of that sort. Do not pick people into your team just because you like them or cuz they are friends with you. If you do, take my word for it, you will ruin the project as well as the relationship.

 

If you like the post, click here to get email alerts when new posts are published.

Did you like the post?Do you agree or disagree with any of these points in particular? Do you have any points of your own to share? Let me know in the comments.