Some thoughts on coding
Recently I had come to the position where I had to refactor the code of o project, because some libraries needed to be updated… While doing this, it was a chance to proceed to a full restructuring. At this point I should add that it was the first project I was ever involved that had to do with Python. In this post I will share some thoughts that were generated from this process. This is in no way a complete coding guide, just some things that annoyed me, you could say a few tips for beginners, but there’s no harm in reminding the (should have been) obvious.
OK… I am used to writing variable names in pascal case, class names in camel case etc… why? because it is more organized to have a certain pattern on the code, because I feel that it’s aesthetically pleasing. Then came the need to share code with some colleagues. When face a similar situation, you quickly understand the need to have a uniform style of coding with everyone else. Lucky for us, most languages come with some kind of coding conventions (sometimes companies have their own coding standards). You can choose to ignore them and code in whatever style you want and be in awe every time you have to look someone else’s code, or use them as guide and pray that everyone will do the same.
To tell the truth, it is not disastrous to write in any way you can think of, but it gets really frustrating when you have to read code that wasn’t written by you if it doesn’t follow some conventions. It gets even worse when the one who wrote it, not only follows different conventions, but also mixes them up. This can also lead to erroneous situations (or better following conventions can help you avoid them). Imaging having a function with x lines where you have to scroll up 3 pages in order to get to the top of it. If you mix variable naming styles, it is easier to have double declarations for the same thing. e.g. you have a variable that will represent a billing receipt. If you follow a certain style, let’s say pascal casing, you will instantly name it billingReceipt. On the other hand, if you don’t follow a certain style, you could end up using billingReceipt in the beginning, BillingReceipt somewhere in the middle and billing_receipt near the end.
Note: I find it somehow childish to see variable names starting with “my” (e.g. my_user, my_nick etc). It reminds me of stupid examples mediocre professors could show you because they couldn’t find better examples. The variable name show pinpoint exactly what’s their use, which leads to the next note.. It’s the 21st century.. the machines are quite powerful, you wont really gain anything by using br instead of billingReceipt. Always keep in mind that there’s the possibility that someone else will have to read and update you code. Make it easy for him, as you would like it to be for you in a similar situation.
DRY (Do Not Repeat Yourself)
To keep it as short… Whenever you find yourself copying and pasting code, just cut it and paste it in a new function. Why having the same code that retrieves an entry from the database be repeated all over the project? Probably once you have done it 2-3 times, you’ll do it many more. And then you’ll have to make a simple change and will have to find all these repetitions and update them… We can already see two benefits: maintainability and development time. Yes, that means that you’ll have to spend less time development AND correcting the code. More time to go out for a beer (or maybe working on cooler stuff than reinventing the wheel)
Taking a step further from the previous tip, we should organize code according to it’s function. The code for the database connection has nothing to do where the code for the UI lays. Nor where business logic is executed. Keep it on it’s natural domain (are you developing on an n-tier architecture? keep in on the DAL, are you using MVC architecture? keep it on the model etc). If the maintainability goτ 1UP from the previous tip this will make it 10 times better. Just think the following case: You are almost done with your application and you manager decides that you’ll have to use y database instead of x. What are you going to do? Scrape everything off and restart? Go through tens or hundred of files accessing the database and update them? Or just rewrite the data access classes in order to access the new database, keeping the the same signatures?
Some time ago, an older programmer told me that code with comments is bad code. It seems a bit awkward when you first hear it, but if you think of it you will realize that code should be written in such a way that a fellow programmer can read it like literature. How can this happen? As stated before, give proper names to the variables, that pinpoint their use. Do the same with the functions, classes etc. There shouldn’t be any doubt what’s their purpose just by looking at their name. Structure the code in a way that the functions don’t get too long and wrap code that has a specific purpose in a well named function, even if it isn’t called in more than one places. The readability of the code will skyrocket and the comments will seem redundant. Keep them only for parts of code that do really bizarre stuff that can’t be explained else ways.
Some programmers are in the habit of organizing the code by using empty lines. Well… don’t… First of all, if the specific section serves a certain purpose, maybe you should consider wrapping it in a function as stated above. Second, additional whitespace adds to the length of the function and could lead to having to scroll up and down in order to read it. This is quite a loss productivity wise. In the best scenario, no function should take more than a screen’s length.
Another bad habit some programmers have is to comment out obsolete pieces of code instead of erasing them, in order to keep them handy in case they want to revert back to it. Well, if the white space was like getting stabbed in the back while coding, this is like getting hit by a semi-automatic. Really, we have a powerful tool called source control (be it SVN, CVS, Git, Mercurial or whatever), why don’t you trust it to do it’s job? Ok.. I understand it if it’s still a work in progress, by them you probably should have committed the code in the first place, let alone having it reach another programmer as in a final state.
None… I just wanted to let out some things that annoy me, and helpfully deter people from making them. If you find it useful, or have anything to add, drop a line in the comments.