Aug
21
11:00 AM
0 Comments
topics:
IT Department,
Software Engineering
Writing FUBAR - What the Hell are Programmers Thinking?
When I first began learning programming, I saw a lot of examples that looked like this:
First let me say that this is the FIRST and LAST time you will see me write code like this. Coding like this is ridiculous. No good programmer writes code like this in the real world. It has somehow been adopted as a standard and acceptable way to teach new programmers how to write code. Unfortunately it is a very bad practice.
Why is it bad practice? Let me give you some reasons.
Teachers teach this type of dribble. But why? I think this comes back to the point above that they are attempting to take the student's attention away from the variables, functions, etc. that are not the point of the example and move focus toward the concept they are really trying to teach. But a good programmer likes to have context for the example. They see more than just the simple mechanics of the code and into the real purpose of it. When you use generic names you sanitize the code to a point that it ceases to be meaningful. Then it becomes more difficult for students to take the example and apply it to a real world situation because they begin to be distracted by questions like "What is this foo and bar thing anyway?"
So what are the principles to keep in mind when writing code (especially examples to teach students)?
What if the code a programmer is writing is generic or abstract?
First of all these abstractions still have names that have meaning within the context of the abstraction. Use those names.
In the event that you have general temporary variables like array indexes, it can be useful to follow industry standards. For example, it is well understood by developers that the letters i, j and k represent array indexes so using those can be acceptable. However, it is still better to use meaningful names like personIndex, propertyIndex and employeeIndex. I have seen (and even made the mistake of using them myself) generic names like i, j and k used and then the programmer gets them mixed up and uses the wrong one causing bugs and confusion. Use of meaningful names helps prevent these accidents.
When you write code for a living / for money, make sure you approach it with a professional attitude. Write it with meaning within the context of your application or library.
When you teach people to write code, expect them to be learning because they intend to do it for a living. There are students that like the academic exercises and understand the generics or abstractions. But most people struggle with them. If you want to really teach effectively, create meaning and use names that fall within the context of that meaning.
As for employers, when you hire someone to write code, make sure they take the professional stance and write code that is easy to understand and maintain. It is an unfortunate fact but well over 90% of the code written by programmers, whether for small projects or for fortune 500 companies, is void of or contains little or useless documentation. Programmers hate to document and businesses don't like paying extra for the effort required to write that documentation.
Hopes this helps you become a better programmer or educator.
Happy coding!
int foo = 5;
int bar = foo * 2;
if (foo > bar) {
System.out.println("You've been foobared!");
}
First let me say that this is the FIRST and LAST time you will see me write code like this. Coding like this is ridiculous. No good programmer writes code like this in the real world. It has somehow been adopted as a standard and acceptable way to teach new programmers how to write code. Unfortunately it is a very bad practice.
Why is it bad practice? Let me give you some reasons.
-
First of all, let's look at what foo and bar really mean and where they come from.
The terms have had a little of a varied origin but in essence they are general purpose
names. They are used when the meaning of the variable, function, etc. is not important
to the understanding of the example.
But this is not how we program and it is not conducive to students' understanding of new programming concepts. In programming, everything has a meaning. And the meaning of the variables, functions, classes and other entities IS important. These generic names can actually lend confusion to the example as the programmer trying to learn the concept struggles with the code because it has no real world context. This context helps ground the student so they can look past the names and to the real substance of the example. I have seen all too often a new programmer get lost in an example like this because it lacks meaning - it is too abstract.
If you have a military background you probably already know an acronym that sounds similar. FUBAR means f**ked up beyond all recognition (or repair). Personally, I don't want my code being though of in this manner and I don't want anyone working for me that wants their code being unrecognizable either. - It isn't practical - no quality programmer writes code like this in the real world. Typically, use of generic names is considered amateurish or simply just bad practice. When people look at code like this they don't understand it and have to spend a great deal of time digging through it in order to determine what it is doing and if it is operating correctly.
- Code should be human readable and names should be meaningful. This is of great importance because the person who wrote the code is inevitably going to hand it off to someone else in the future. Unless the application or chunk of code is thrown away, you will have multiple programmers have to read and possibly change or enhance the code. Make sure it takes as little time as possible for someone new to understand what is going on or they will waste a lot of time just trying to understand what the code is doing.
- Often programmers think it is funny or cool to write code this way. Being funny, cute or somehow "cool" gets in the way of getting the job done. It is childish and demonstrates a lack of professionalism. Programmers should keep this type of behavior at home and out of the office. I am not trying to take the fun out of it. I am just saying that this behavior works to the detriment of others and can cost the business. By all means have fun but don't create problems for other team members.
-
If you are teaching, remember that students should learn how to code in the classroom the
same way they will code in the real world. People mimic what they are taught. If you
teach programmers to write foo and bar, they are likely to carry this type of practice over
to the working world (at least until they are corrected and learn how to write code
properly which they should have done in the classroom).
Just how hard is it to create real world examples? They don't have to be amazing works of software engineering, they just need to have some sort of real meaning. Yes, it will take a little effort but not much. And if you run short of ideas, just Google it. There are bound to be some great examples that have some real world application.
Teachers teach this type of dribble. But why? I think this comes back to the point above that they are attempting to take the student's attention away from the variables, functions, etc. that are not the point of the example and move focus toward the concept they are really trying to teach. But a good programmer likes to have context for the example. They see more than just the simple mechanics of the code and into the real purpose of it. When you use generic names you sanitize the code to a point that it ceases to be meaningful. Then it becomes more difficult for students to take the example and apply it to a real world situation because they begin to be distracted by questions like "What is this foo and bar thing anyway?"
So what are the principles to keep in mind when writing code (especially examples to teach students)?
- First, find a real or at least close to real world example. Yes this takes a little more work than coming up with some generic meaningless code snippet. However, it will help new programmers put the code into context and will even make it more interesting. Academic types tend to love this more generic approach and if you are trying to create some sort of reusable abstraction it can be a good academic exercise. However, most people don't think this way and need real meaning. ("Meaning," am I using that word too much yet?)
- Use names that have meaning (there is is again, let me use it some more) and lend to reading the code like it were a book. This is very important when adding new programmers and swapping staff on and off a project. If you are an employer you know you WILL have people come and go in the business and you WILL have to put new developers on old code.
- Make sure you have peer review sessions. This is where one programmer reviews the code of another programmer. This is an excellent exercise for finding readability problems. It is not uncommon that a programmer writes something they think is readable but is hard to understand by another. It happens to even the best of us. It is also great for finding bugs and helping programmers share ideas on how to write great code so there are benefits beyond just checking readability.
What if the code a programmer is writing is generic or abstract?
First of all these abstractions still have names that have meaning within the context of the abstraction. Use those names.
In the event that you have general temporary variables like array indexes, it can be useful to follow industry standards. For example, it is well understood by developers that the letters i, j and k represent array indexes so using those can be acceptable. However, it is still better to use meaningful names like personIndex, propertyIndex and employeeIndex. I have seen (and even made the mistake of using them myself) generic names like i, j and k used and then the programmer gets them mixed up and uses the wrong one causing bugs and confusion. Use of meaningful names helps prevent these accidents.
When you write code for a living / for money, make sure you approach it with a professional attitude. Write it with meaning within the context of your application or library.
Here's a dirty little secret: Programmers hate to write documentation. What I have found is if you use meaningful names and write code so that it almost reads like a book, you don't need very much documentation for other programmers to be able to understand, use and maintain that code. However, the more generic or abstract the code, the greater the amount of documentation must be written.
Tell your programmers that unless they want to write lots of documentation, they should make their code easily readable, simple and easy to follow. They will be eager to write easy to read code.
When you teach people to write code, expect them to be learning because they intend to do it for a living. There are students that like the academic exercises and understand the generics or abstractions. But most people struggle with them. If you want to really teach effectively, create meaning and use names that fall within the context of that meaning.
As for employers, when you hire someone to write code, make sure they take the professional stance and write code that is easy to understand and maintain. It is an unfortunate fact but well over 90% of the code written by programmers, whether for small projects or for fortune 500 companies, is void of or contains little or useless documentation. Programmers hate to document and businesses don't like paying extra for the effort required to write that documentation.
Hopes this helps you become a better programmer or educator.
Happy coding!
Posted By Aaron Bono
