Comments are Important

Say hello to your friend, the comment.

// Comments will make your life a lot easier.

Don’t be afraid to use a lot of comments.
They can only help.

I know writing comments is extra work. For those of use who don’t have perfect typewriting skills (and with the QWERTY keyboard, who does?). But they are extremely valuable.

(Zemanta tells me that I should add this link: 7 Reasons to Switch to the Dvorak Keyboard Layout. Personally, I’d prefer the Programmer’s Dvorak, if I can ever set up Ukelele to work properly. Who knows what I’m talking about???)

I write convoluted code. I have a hard time following MVC. It’s a fact of life. I easy this problem significantly by using comments. Trust me—I was skeptical about comments. Why should I write comments? I know what my code does! Uh…no I don’t. It’s a simple fact of a programmer’s life that we start to forget about what our code does. Or why that code works the way it does. By adding comments at the beginning of every few lines, or even a few tabs away from the end of every other line, it makes my job so much easier.

Trust me. Comments are worth the extra effort.

Don’t Write Confusing Code

Here is a very important lesson that I’ve just begun to learn:

Don’t write confusing code.

Make sure you know exactly what you plan to do. Think it out, make a solid plan, and organize it mentally. As Wil Shipley of Pimp My Code (See my Links page) says, you have to know exactly what you’re going to do, before you do it. To paraphrase, your new project is a clean slate. Every line of code is a filthy black streak. I guess every line of ugly code is a scratch…?

As I work on an app for a friend, I realized that I haven’t planned enough. As a result, a lot of my code is very convoluted, to the point where I can’t figure out the logic behind it at all. There’s too much for me to want to re-write—it’s just a huge mess that it ends up being. Had I known what I wanted every piece of code to do, I wouldn’t be in this mess.

So how would I recommend doing this? Simple—plan out all the steps as if you were manually doing them. Then, convert to code. To paraphrase Mr. Shipley again, instead of writing if (something is true) then (doing this, something, and that), write if (something is not true)…apparently it is more natural that way. I’ll let him explain:

Don’t indent and indent and indent for the main flow of the method. This is huge. Most people learn the exact opposite way from what’s really proper — they test for a correct condition, and if it’s true, they continue with the real code inside the ‘if’.

What you should really do is write ‘if’ statements that check for improper conditions, and if you find them, bail. This cleans your code immensely, in two important ways: (a) the main, normal execution path is all at the top level, so if the programmer is just trying to get a feel for the routine, all she needs to read is the top level statements, instead of trying to trace through indention levels figuring out what the “normal” case is, and (b) it puts the ‘bail’ code right next to the correctness check, which is good because the ‘bail’ code is usually very short and belongs with the correctness check.

When you plan out a method in your head, you’re thinking, ‘I should do blank, and if blank fails I bail, but if not I go on to do foo, and if foo fails I should bail, but if not i should do bar, and if that fails I should bail, otherwise I succeed,’ but the way most people write it is, ‘I should do blank, and if that’s good I should do foo, and if that’s good I should do do bar, but if blank was bad I should bail, and if foo was bad I should bail, and if bar was bad I should bail, otherwise I succeed.’ You’ve spread your thinking out: why are we mentioning blank again after we went on to foo and bar? We’re SO DONE with blank. It’s SO two statements ago.

Thank you, Mr. Shipley. Don’t write confusing code.

Edit: Etresoft below has made an important point. I also think I didn’t quite make myself perfectly clear. As I’ve said about my project for my friend, I jumped in, without proper planning. That, coupled with poor logic, is resulting in a mess that I’m fighting to pull myself out of right now. I believe that any app needs a good dose of UI design and even class diagrams—plus a good amount of reasonable logic. Don’t make code more convoluted than it needs to be.

Also, I tend to re-write a lot of code in if-else statements…that’s just more room for error, and makes code harder to manage. It was easier to do that the first time around, rather than figuring out exactly what I needed to put in the if-else.

Don’t take the easy way out, and trade that off for convoluted code.

With more experience, I may end up doing a reprise of this post. Etresoft’s right—I do learn through mistakes.


Instructions for Reading this Blog

These are actually copied out of Donald Knuth’s The Art of Computer Programming, Volume I. No copyright infringement is intended. This is considered fair use, under the category of “Educational.” It is very enlightening.

  1. Begin reading this procedure, unless you have already begun to read it. Continue to follow the steps faithfully. (The general form of this procedure and its accompanying flowchart will be used throughout this book.)
  2. Read the Notes on the Exercises, pp. xvii-xix.
  3. Set N equal to 1.
  4. Begin reading chapter N. Do not read the quotations which appear at the beginning of the chapter.
  5. Is the subject of the chapter interesting to you? If so, go to step 7; if not, go to step 6.
  6. Is N ≤ 2? If not, go to step 16; if so, scan through the chapter anyway. (Chapters 1 and 2 contain important introductory material and also a review of basic programming techniques. You should at least skim over the sections on notation and about MIX).
  7. Begin reading the next section of the chapter; if you have reached the end of the chapter, go to step 16.
  8. Is the section number marked with “*”? If so, you may omit this section on first reading (it covers a rather specialized topic which is interesting but not essential); go back to step 7.
  9. Are you mathematically inclined? If math is all Greek to you, go to step 11; otherwise go to step 10.
  10. Check the mathematical derivations made in this section (and report errors to the author). Go to step 12.
  11. If the current section is full of mathematical computations, you had better omit reading the derivations. However, you should become familiar with the basic results of the section; these are usually stated near the beginning or in italics right at the very end of the hard parts.
  12. Work the recommended exercises in this section in accordance with the hints given in the Notes on the Exercises (which you read in step 2).
  13. After you have worked on the exercises to your satisfaction, check your answers with the answer printed in the corresponding answer section at the rear of the book (if any answer appears for that problem). Also read the answers to the exercises you did not have time to work. Note: In most cases it is reasonable to read the answer to exercise n before working on exercises n + 1, so steps 12-13 are usually done simultaneously.
  14. Are you tired? If not, go back to step 7.
  15. Go to sleep. Then, wake up, and go back to step 7.
  16. Increase N by one. If N = 3, 5, 7, 9, 11, or 12, begin the next volume of this set of books.
  17. If N is less than or equal to 12, go back to step 4.
  18. Congratulations. Now try to get your friends to purchase a copy of volume one and to start reading it. Also, go back to step 3.

Here is the corresponding flowchart:

The Art of Computer Programming—Reading Flowchart

Why did I post this? Obviously, you wouldn’t read the blog in this manner. But the open-minded approach is exactly what I’m looking for. In programming, you have to be open-minded, and look for a different solution. This is the attitude that I convey when I’m writing this blog, or coding at home; I’d appreciate the same from all my readers.

Oh, and of course, I recommend that everyone pick up a copy of Knuth’s masterpiece. He began working on it in 1962, and he’s just past half-way finished (in terms of volumes). Appreciate all the work. Take it in.

Onward Ho!

As summer fades into the dreardom (dreariness, for those who prefer real, “dictionary” words) of fall, I figure that it would be a good time to add one more task to my already busy schedule.  I’m hoping to make this blog a fun experiment, not a chore.

Over the next few days, I’ll start putting up some actual content. I plan on beginning with a bit of theory and art, then I’ll start with a series on learning Obj-C 2.0. I’ll then move on to exploring Foundation, Cocoa Touch, and then…we’ll see. I’m going to enjoy this, and I hope you, dear reader, will too.

Onward ho!

  • Welcome

    My goal is to make CupsOfCocoa into a beautiful source for beginners to the iPhone platform to get started. Subscribe below for more, and stay tuned!

  • Contact Me

    If you need to contact me for any reason, feel free to send me an email.
  • The Giving Spirit

    If you've found this site helpful, would you consider donating a little sum? Any amount is appreciated...Thanks so much!

  • Roadmap

  • Enter your email address to follow this blog and receive notifications of new posts by email.

    Join 220 other followers

  • Back to the Past

    August 2010
    S M T W T F S
  • Time Machine

  • You count!

  • Worldwide Stats

    free counters
%d bloggers like this: