Career
5 Types of Comments to Avoid Making in Your Code
Have you ever been reviewing code and come across a comment that you deemed was unnecessary? Commenting your code is meant to improve the readability of your code and make it more understandable to someone other than the original developer.
I have identified 5 types of comments that really annoy me and the types of programmers who make them. I hope after reading this you won’t be one who falls into one of these categories. As a challenge, you can try to match up these comment programmers with the 5 types of programmers.
1. The Proud Programmer
{
static void Main(string[] args)
{
string message = "Hello World!"; // 07/24/2010 Bob
Console.WriteLine(message); // 07/24/2010 Bob
message = "I am so proud of this code!"; // 07/24/2010 Bob
Console.WriteLine(message); // 07/24/2010 Bob
}
}
This programmer is so proud of his code that he feels the need to tag every line of code with his initials. Implementing a version control system (VCS) allows for accountability in code changes, but at first glance it won’t be so obvious who is responsible.
2. The Obsolete Programmer
{
static void Main(string[] args)
{
/* This block of code is no longer needed
* because we found out that Y2K was a hoax
* and our systems did not roll over to 1/1/1900 */
//DateTime today = DateTime.Today;
//if (today == new DateTime(1900, 1, 1))
//{
// today = today.AddYears(100);
// string message = "The date has been fixed for Y2K.";
// Console.WriteLine(message);
//}
}
}
If a piece of code is no longer used (i.e. Obsolete), delete it – don’t clutter your working code with several lines of unnecessary comments. Besides if you ever need to replicate this deleted code you have a version control system, so you can recover the code from an earlier revision.
3. The Obvious Programmer
{
static void Main(string[] args)
{
/* This is a for loop that prints the
* words "I Rule!" to the console screen
* 1 million times, each on its own line. It
* accomplishes this by starting at 0 and
* incrementing by 1. If the value of the
* counter equals 1 million the for loop
* stops executing.*/
for (int i = 0; i < 1000000; i++)
{
Console.WriteLine("I Rule!");
}
}
}
We all know how basic programming logic works – this is not “Introduction to Programming.” You don’t need to waste time explaining how the obvious works, and we’re glad you can explain how your code functions – but it’s a waste of space.
4. The Life Story Programmer
{
static void Main(string[] args)
{
/* I discussed with Jim from Sales over coffee
* at the Starbucks on main street one day and he
* told me that Sales Reps receive commission
* based upon the following structure.
* Friday: 25%
* Wednesday: 15%
* All Other Days: 5%
* Did I mention that I ordered the Caramel Latte with
* a double shot of Espresso?
*/
double price = 5.00;
double commissionRate;
double commission;
if (DateTime.Today.DayOfWeek == DayOfWeek.Friday)
{
commissionRate = .25;
}
else if (DateTime.Today.DayOfWeek == DayOfWeek.Wednesday)
{
commissionRate = .15;
}
else
{
commissionRate = .05;
}
commission = price * commissionRate;
}
}
If you have to mention requirements in your comments, don’t mention people’s names. Jim from sales probably moved on from the company and most likely the programmers reading this won’t know who he is. Not to mention the fact that it everything else in the comment is irrelevant.
5. The Someday Programmer
{
static void Main(string[] args)
{
//TODO: I need to fix this someday – 07/24/1995 Bob
/* I know this error message is hard coded and
* I am relying on a Contains function, but
* someday I will make this code print a
* meaningful error message and exit gracefully.
* I just don’t have the time right now.
*/
string message = "An error has occurred";
if(message.Contains("error"))
{
throw new Exception(message);
}
}
}
This type of comment is sort of a catch-all it combines all the other types. The TODO comment can be very useful when you are in the initial development stages of your project, but if this appears several years later in your production code – it can spell problems. If something needs to be fixed, fix it now and do not put it off until later.
If you are one who makes these types of comments or would like to learn best practices in comment usage, I recommend reading a book like Code Complete by Steve McConnell. This is one of the books that I recommend all programmers should own.
Or Perhaps you can learn how to stop commenting your code altogether.
Do you see any other unnecessary or annoying comments in your code? Please feel free to share.
Update (11/11/11): I found some additional funny code comments: 10 “Best” Code Comments
59How to Get Started with Windows SharePoint Application Development
I’ve made it a goal to become certified in Windows SharePoint Services 3.0 – Application Development by the end of the month.
The Setup
I am fortunate to have access to Microsoft DreamSpark, which provides students access to full versions of the latest Microsoft development tools. I believe the only requirement is that you have an active student email address.
To setup my environment, I installed the following:
- Microsoft Windows Server 2003
- Internet Information Services (IIS)
- Microsoft Visual Studio 2008
- Windows SharePoint Services 3.0 with SP2
Learning
My primary source of learning will be reading the following book (available via Amazon.com and through ACM subscription:
Inside Microsoft Windows SharePoint Services 3.0
Ted Pattison and Daniel Larson
The book also contains a companion CD with examples.
1Get Hired By Solving Programming Puzzles
When it comes to down to it practice makes perfect. In order to become a successful programmer you need to keep your skills up-to-date and work on problems outside of those faced at work.
Luckily, there are numerous websites that provide the opportunity to practice. The following blogs comprehensively list most of the puzzle websites that are available to help you practice your skills.
- 5 Resources for Refining Your Programming Skills (via rbright.net)
- Practice Your Code-Fu: Programming Contests and Puzzles Online (via grok-code.com)
- 10 Puzzle Websites to Sharpen Your Programming Skills (via sixrevisions.com)
- 10 More Puzzle Websites to Sharpen Your Programming Skills (via coderholic.com)
There is one other website that is absent from the lists above that provides programming puzzles.
ITA Software is a company based out of Cambridge, MA that specializes in the development of airline and travel software. They use programming puzzles to attract and recruit new employees.
They won’t grade your solution if aren’t considering working for them, but that doesn’t mean that you can’t at least try implementing a solution. The puzzles are designed for those looking for a challenge.
If you are ready for the challenge, ITA has two sets of puzzles:
If you have attempted these problems or have been hired as a result of completing one of the problems, please share your experiences.
What Programmers Can Learn From Salespeople
Screenshot courtesy of: The Secret of Monkey Islandâ„¢
What comes to mind when you hear the terms: ‘Salesman’, ‘Salesperson’ or ‘Sales’ ?
- High-Pressure
- Negotiation
- Cold-calling
- Telemarketing
- Spam
If these are the type of words that come to mind, you have probably been dealing with some bad salespeople.
What is Sales?
I do not work nor have I ever worked in sales, but I have taken sales classes offered by my employer.
If there was one thing I learned about sales, it’s that the sales process is more about having a conversation than it is about buying or selling something.
How does this relate to programming?
Before you see how to this relates to programming, you must be able to think like someone who is motivated more by helping people rather than by money.
The Financial Planner
The scenario to understanding genuine salespeople is to look at a financial planners. If you are unaware of what financial planners do – they advise individuals in making major financial decisions such as retirement, taxes, investing, etc.
When you visit a financial planner, you could tell him or her that you want to retire by age 50 and you want to invest $100 per month. Without any further discussion, a financial planner could come up with a solution for your retirement, but is it going to be the best solution?
The Programmer
Any good programmer can take requirements and a design and develop a solution that meets the needs that are laid out. But is this what the end-user really wanted?
What if you actually sat down with the end-user and had a conversation with him or her rather than rely on some specs that a business analyst obtained?
You might be thinking to yourself, isn’t that the job of the business analyst? In an ideal world it would be, but like the Game of Telephone (or Chinese Whispers) something is going to get lost in translation going from end-user -> Business Analyst -> Programmer.
If you have the opportunity to have a conversation with the end-user, take it. Establish a relationship, listen to them to find out what they really need, negotiate possible solutions and close by building them a solution.
Listen Carefully
The most important part about sales and also with programming is: listening.
Don’t be the used-car salesperson who wants to sell the heap of junk on the lot, without understanding the true needs of the customer.
What I’ve Learned from Teaching Programming
I am not a teacher, professor, trainer, etc. but I recently was afforded the opportunity to teach programming to my co-workers.
At work we started doing more and more development in .NET. I previously acquired skills in .NET from a previous employer. My co-workers had minimal exposure to .NET and object-oriented programming.
My boss approached me to ask if I’d liked to teach ASP.NET to the rest of my co-workers. Naturally, I accepted because I thought teaching would help reinforce my skills.
The Setup
Lesson Planning
I got started learning .NET from studying for my MCTS, so I decided to prepare 10 one-hour lessons based on topics from the Microsoft Press books:
MCTS Self-Paced Training Kit (Exam 70-562): Microsoft® .NET Framework 3.5 ASP.NET Application Development
MCTS Self-Paced Training Kit (Exam 70-536): Microsoft® .NET Framework Application Development Foundation
Since many of my co-workers had not been exposed to object-oriented programming, I made the first lesson an overview. I knew that this would be vital to understanding the .NET framework. For this I just used Wikipedia as a resource.
The conclusion of each lesson was a “homework” problem using the techniques explained in the lesson.
Teaching Environment
Many of my co-workers work remotely, so teaching via the web was the best means. To facilitate this, I used the services of Dimdim for web conferencing in combination with a teleconference bridge.
Successful or Not?
I ended up delivering teaching all of my lessons. There were times where I had technical difficulties where the web conference experience lag time or my lesson samples wouldn’t produce the expected results. Through preparing each week’s lessons I reinforced my .NET knowledge and studied beyond what I was teaching to make sure I could explain any questions that may have been asked.
So my delivery was (mostly) successful and I learned a lot, but are these the criteria in which to measure success?
Feedback
What was missing from my teaching methods was the feedback of my co-workers. I never took it upon myself to ask them if they were learning. When you are teaching in a corporate environment it is difficult to gauge the progress of your “students”.
It would’ve helped me if I knew my lessons were heading in the right direction. I’ve asked my co-workers at the end of all the lessons what they got from my teaching, but by that time it was too late.
A couple of the responses I received were:
It’s difficult to learn a new programming language unless I’m using it for a project.
I tend to get distracted when learning via webinar.
Things I Would Do Differently
I think a classroom setting would be the ideal environment for teaching/learning. This may be costly especially if you have remote employees. Given this experience with teaching via webinar, I sometimes wonder about the quality of some online degree programs.
I also could have given an exam to ensure my co-workers were paying attention and/or grasping what I was teaching, but I think asking a more effective way would be to get them involved by asking specific questions or having them work hands-on in a classroom.
By becoming a teacher (if only through work), I know understand the importance of feedback/evaluation. In academia, most teachers and professors will require an evaluation at the conclusion of a class, but I think continual evaluation would be most beneficial for the student and the teacher.
The teacher can adjust his/her teaching style to adapt to the students and the students will be able to comprehend what they are learning.
What Programming Language Should I Learn Next?
I am a big fan of reddit and it is usually my primary source of reading what’s new.
There is a sub-category (sub-reddit) on Reddit for Programming and one question that is posed very frequently is: What programming language should I learn next?
If your purpose for learning a new language is career motivated, I recommend that you start your quest looking at what what top companies are searching for in candidates. Companies such as Microsoft, Google and and Apple will generally seek individuals who have knowledge of the core programming languages such as C, C++, Java and will mix in some of the more cutting-edge technology such such as AJAX or jQuery.
Here are some sample job requirements from Google, Microsoft, Facebook and Apple.
Google - Software Engineer
- BS, MS, or PhD in Computer Science or related technical discipline (or equivalent).
- A solid foundation in computer science, with strong competencies in data structures, algorithms, and software design.
- Extensive programming experience in C/C++ and/or Java (strong OO skills preferred).
- Several years of large systems software design and development experience, with extensive knowledge of Unix/Linux.
- Coding skills in Python or Javascript/AJAX, database design and SQL, and/or knowledge of TCP/IP and network programming are a plus.
Facebook – Front-End Engineer
- A passion for performance debugging and benchmarking Experience building JavaScript/HTML/CSS applications and frameworks
- Experience working with JavaScript/HTML/CSS in high-performance environments
- Knowledge of but not reliant on Prototype JS, MooTools, Dojo, jQuery
- Identify performance bottlenecks in JavaScript applications
- Build performance minded front end abstractions and systems
- Provide code optimization recommendations
- Prototype and implement optimization techniques
- Benchmark existing code and enhancements
- Participate in design and code reviews
- Code primarily in JavaScript, HTML & CSS
- Interface with other team members to incorporate their innovations and vice versa
- Identify and communicate best practices interpersonal and communication skills, and proven ability to work effectively with all organizational levels
- BS or MS degree in Computer Science or Engineering preferred
Microsoft – Software Development Engineer (SDE)
- Pursuing a B.S./M.S. or Ph.D. degree in Engineering, Computer Science, or related field
- 1-2 years experience programming in C/C++/C#, Java, and/or other computer programming languages preferred
- Ability to derive creative and innovative solutions by thinking “outside the boxâ€
- Expertise in feature definition, design, and feasibility
- Demonstrated skill in estimating development time
Apple - Application Software Engineer
Key Requirements:
- BS CS/CE or equivalent
- Strong programming skills, preferably with C, Objective-C, and/or C++
- Excellent communication and collaborative skills
- Excitement and passion to work on amazing products
- Deep understanding of performance assessment and optimization
- Proven ability to excel in a fast-paced development team
Preferred skills:
- Mac OS X and/or iPhone OS programming experience
- User-interface programming experience
- Familiarity with web technologies and XML
By reviewing the job postings of the leaders in technology, you should be able to get a good idea of what is in demand these days.
I know from past experience when I looking for a job, I often saw postings that listed every programming language known to man: Cobol, Fortran, Pascal, QBasic, C, C++, C#, VB, VB.NET, Java, PHP, Perl, Python, Ruby, etc. Any not only that, they were looking for 10+ years experience in each one. These types of postings are unrealistic, not to mention ridiculous – it is highly unlikely that anyone has all the required experience (especially 10 years of .NET).
There is nothing wrong with learning an outdated or obsolete programming language for fun – I encourage it, if you have the time to learn it. But for advancing your career, a solid understanding of a core language is key.
Beyond programming skills, you might decide to acquire skills in another area such as development estimation, code design, or something non-technical such as communication skills.
How do you decide what you are going to learn next?