Mostly Harmless

Some Comments About Commenting

2007-05-21T21:04:00.000+03:00

Lately I have seen far too much undocumented code. It seems that no one really appreciates the power of good commenting anymore.

I'm a pretty good coder, I think, and so are many of the people I work with. But for some odd reason, I don't remember anyone taking comments as seriously as I do.

Commenting is what makes the difference!
Comments are the difference between good code and excellent code, and as such, they make the difference between a good coder and an excellent coder.

Nobody like to comment their code, and I really don't know why, but I suspect a part of the problem is not knowing how to comment code in a good manner, or not recognizing good comments when you see them.

So I've decided to compile a short list of tips for the common coder, who now have to sit and write some comments for the first time in his life.
Here they are, from least important to most important:

9 Tips for Good Commenting

9. Don't write too long, but don't write too short

Writing "War and Peace" in your code will not do anyone good, everybody knows that.
But more often, you will find out comments that are simply not helpfull, all in the name of shorthand writing.

Writing "sets X according to the database value" is far better than "this line of code sets X according to the value that was returned from the database", no doubt about it. However, how many times did you see a comment that said "sets X" and that's it? Writing those extra 5 words won't cost you more than a few seconds, and can save a lot of time to whoever it may be that will read your code in the future.
It might even be you...

8. Not all comments must be operational

Not all your comments need to describe exactly what happens in the next line.
Comments like "don't forget to set variable X", "to activate these settings you must call function F" or "this code affects function F2" can sometimes be more helpful.

Keep in mind that sometimes code segments are copy-pasted - not a best practice, but it happens a lot - and it could help to know which other places the copied code segment affects.

7. Don't leave dead code in comments

If you don't need it, delete it. I know it's hard, but just let it go...

If you have some brilliant piece of code you just have to keep for the next generations, just in case they will need to do something like that in some other place - you can put it on external documentation, write an email, or post it in your favorite forum. If it's not used, don't keep it in the code!

If you suspect a line of code will be necessary in the very near future, you can leave it, but explain what it does. Write a comment before the dead code that makes it crystal clear why you left it there.

6. Beware of copy-pasted comments

Come on, guys, this is the oldest trick in the book. We've all suffered from copy-pasted code gone bad. However, copy-pasted code gone bad usually get fixed quickly, since it's bound to be discovered sooner or later. Copy-pasted comments, on the other hand, just stay in the code and get rotten.

You copy a block of code, with comments, and you just change the variables you need in the code, and you end up with a comment that has nothing to do with the code. The next time anyone will look at this code he wouldn't understand where the comment came from, so he might leave it as it is "just in case"...

5. Use correct language

This is a problem especially with non-native English speakers, that must write their comments in English (such as myself).
I don't expect the comments to demonstrate impeccable writing skills in a foreign language, but every one that has basic understanding of the language can tell the difference between "returns the X object if it exists" and "object X to return or null".

Even if the comment can be understood without using proper English, it will take an extra second or two to understand it. It could also cause mistakes simply because the person who read the comment didn't understand it correctly. Not a life or death matter, but it is still very important.

4. Don't be afraid of repeating yourself

Don't be afraid of repeating yourself. Over and over again, when necessary. The same sentence can appear in 4 different procedures, and maybe a couple of times in the same procedure. Remember, probably nobody will ever read your code like a storybook, as a whole. The reader will not mind that some comments repeat themselves. Sometimes the reader will only look at one part of your code, at one specific function.

It's OK to write the meaning of a variable or parameter in the constructor, setter, and every function that use it. It's more than OK, it's better to do so than to write the meaning of the variable only once in some private function that is only used way down the call stack. This way the programmer will not need to drill down only to discover the meaning of a parameter he is using.

So again, when commenting, don't be afraid of repeating yourself.

3. Don't be afraid to comment the obvious

The important point here again is that nobody will read your code like a book. Nobody will be upset if you write a comment stating the obvious. The fact is for most programmers, even the most experienced, it is easier to read natural language than code. That's just the way the human mind works.

Try to read this simple code and you will understand:

private int multi(int a, int b)
{
   return a*b;
}

You could guess from the name that this function multiplies two numbers.
However, you could not be sure until you read the whole function.
If you read the following example instead:

// This function multiplies two numbers
private int multi(int a, int b)
{
   return a*b;
}

You only have to read the first line to understand it.
If you have a comment for every couple of rows in your code, you don't have to delve into the code every time to understand it, you can find the part you need quickly.

This example may seem a little silly, but this is the same for 5 rows long functions or 50 rows long functions, and hopefully you don't have functions much longer than that in your code :)

2. Comment the why, not only the how

OK, now we are getting serious. Whenever we comment a piece of code, we should not only comment what we are doing and how, we should also comment why we are doing what we are doing.

I have a couple of way to comment this method:

public MyClass(int myProp1, int myProp2, string myProp3)
{
   this._myProp1 = myProp1;
   this._myProp2 = myProp2;
   this._myProp3 = myProp3;
}

I could comment the how:

// This is the constructor for class MyClass
public MyClass(int myProp1, int myProp2, string myProp3)
{
   // initialize private properties
   this._myProp1 = myProp1;
   this._myProp2 = myProp2;
   this._myProp3 = myProp3;
}

But I better comment the why:

// This is the constructor for class MyClass.
// This class does this and that. 
// Classes that creates MyClass should do X, Y and Z.
public MyClass(int myProp1, int myProp2, string myProp3)
{
   // initialize private properties:
   // _myProp1 controls this behavior
   this._myProp1 = myProp1;
   // _myProp2 controls that behavior
   this._myProp2 = myProp2;
   // _myProp3 is displayed on screen when X happens.
   // It can be omitted, and then the default message
   // is displayed.
   this._myProp3 = myProp3;
}

Isn't that a lot better? When reading this code, I know why I need to initialize myProp1 in the constructor, and what is the purpose of doing so.

Commenting the why is the key for good commenting. If you take only one thing from this post, take this.
Programmers are not idiots. They can read code - and if they can't, it won't help no matter how much comments you give them. But a line of code cannot express the meaning or spirit of the whole program. This is why you should comment, to explain the place of this specific line of code in the overall stucture of your system.

And now, for the number one tip of good commenting...

1. Comment

...As opposed to "do not comment", of course.

You know what they say, practice makes perfect - so start commenting today!

Make it a habit to comment your code when you are writing it, not afterwards. It always helps to think a little before you code. So while you're at it, planning how your code will work and all the bits and bytes, you already know why you need to write this piece of code. You know it now, but tomorrow you may forget. Someone else that will look at the code will not know. So tell him why you wrote it, and what it is supposed to do.

Believe me, before you know it you will not be able to code without commenting.

I hope this helps, and if a single helpful comment was born as a result of my post, my work here is done :)

מפנה מקום באייפוד לשירים שלך

2007-01-20T21:49:00.000+02:00

אם ברי סחרוף היה כותב היום את השיר "מפנה מקום", מעניין אם הוא היה נשמע כך:

אני מפנה מקום בנייד למספרים שלך
מפנה מקום בדיסק למסמכים שלך
מפנה מקום באייפוד לשירים שלך
מפנה מקום במסך בשביל הרקע שלך
אני מפנה מקום באימייל למכתבים שלך
מפנה מקום במסנג'ר לחברים שלך
מפנה מקום בבלוג לתגובות שלך

כל כך הרבה מקום, ואת בשלך... את בשלך

כל כך הרבה מקום
את יכולה לעשות לוג-און
ואם תהיי לגמרי שלי
אני אצטרך לקנות עוד דיסק-און-קי

וובכן, מזל שהשיר הוקלט בשנת 1995 ולא 2005.

פח הזבל של האנושות

2006-11-15T16:21:00.000+02:00

הפסקתי לקרוא בלוגים.
ניתקתי את האינטרנט.
כיביתי את המחשב.

יום אחד קמתי בבוקר ואמרתי "די!".
די לפשפש בערימות הזבל, לזפזפ בין גרפומנים מקושקשים לאנשי דעת רהוטים, לקרוא עוד ועוד בלוגי מציאות, בלוגי כלכלה, בלוגי טכנולוגיה, בלוגי אמנות ובלוגי מדע וטבע.
שוב ושוב אתה מוצא את עצמך בוהה במסך המרצד בשעות הקטנות של הלילה, תוהה לאן נעלמו להן שוב 3 או 4 שעות מחייך, וממלמל לעצמך בלחש "רק עוד אתר אחד קטן... רק עוד אחד".
ההומור כבר אינו מצחיק, החדשות דרמטיות מדי, הריאליטי נדוש מדי, והדברים אותם אתה "לומד" בשיטוטים האינסופיים נעלמים מראשך באותה המהירות שבה מתעדכנים האתרים, כלומר מדי יום ביומו.

והפרסומות, אלוהים, הפרסומות!
קופצות עליך בין כל קליק לקליק, אורבות לך בנבכי האתרים, מפמפמות לך במוח באופן בלתי פוסק, ואתה, כארנב שנלכד באורם של פנסי המכונית, בוהה ובוהה וממשיך לחפש באופן נואש את הכפתור הקטן הזה עם האיקס.

מכירים את אלו?
בטח, כל אחד מכיר אותם.
"הפסקתי לראות טלויזיה", הם אומרים.
"התנתקתי מהכבלים!", הם מכריזים (מיד לפני שהם מצהירים שסחבק - ישראלי או לא? - מוריד את כל התוכניות שהוא הכי אוהב בחינם לגמרי בפרד האלקטרוני).
"נמאס כבר מהפרסומות", הם מתלוננים, ובצדק.
"הזבל שמציף אתכם מבוקר עד ליל ומזהם לכם את השכל", קורא לזה דרור פויר, בעוד הוא עצמו שוקד על הוספת תכנים (משובחים ככל שיהיו) לפח הזבל הגדול של האנושות, פח הזבל שאיש אינו טורח לרוקנו, פח הזבל שכל אדם יכול לצקת בו תוכן ללא כל הכשרה רשמית או גוף מכוון, פח הזבל שאותו לא מתסרטים, לא עורכים, לא מגיהים ובוודאי לא מסננים.

חלק גדול מ 12 מיליארד או יותר העמודים באינטרנט - בערך פי 2 ממספר האנשים בעולם, כולל אפילו את נמיביה - נכתב בידי אנשים משכילים ובעלי כשרון, ומהווה באופן כללי מה שאדם בר דעת היה בוודאי מכנה כ"לא זבל".
טוב, נו, אולי לא חלק גדול. חלק קטן. קטן מאוד. מזערי.

ועם זאת, אפשרי ואפילו רצוי לצרוך במידה מסוימת את אותו חלק קטן של תרבות אינטרנטית איכותית, כשם שאנו צורכים מדיות אחרות כגון מוזיקה, קולנוע, תיאטרון וספרות.

אז לא, אני עדיין לא ויתרתי על הבלוגים.
לא ניתקתי את האינטרנט ולא כיביתי את "מכשיר הטמטום" של המאה ה 21, המחשב.
כשם שלא ניתקתי את הלווין, לא כיביתי את הטלויזיה ולא הוצאתי אותה מן הבית.

את הסינון בין טוב ורע, בין מועיל ומזיק, בין ניצול זמן ובזבוז זמן, אני כבר אצטרך לעשות בעצמי - מה לעשות, החיים קשים בשנות האלפיים.

Bidirectional Blogging

2006-09-02T01:52:00.000+03:00

When starting this blog, I was really concerned about writing a blog in two languages - English and Hebrew. As the title suggests, the problem is not using two different languages but actually writing in two different directions - left to right and right to left.

Unfortunately, searching the web for a little while yields no real solution for us bidirectional bloggers out there (I can only assume the Arabic blog scene propose no solution either).
I am sure some bloggers have sorted this out by themselves, while the others chose to align all of their posts to one direction or the other, regardless of the language they are written in. Another easy solution could be starting a different blog for each language. But that wasn't good enough for me.

The Blogger system, as I suppose other blogging platforms as well, provides the blogger with almost absolute control over the graphic design and layout of the page. It is done by means of a "Template" which is basically some html code with special tags inside, which is actually very similar to web scripting languages like ASP.

I was very pleased to find out Blogger allows javascript code to run from within the template, which among other things can solve this problem for all you bidirectional bloggers.

So, let's say you want to align every post with English text in it to the left, and any other post to the right. Here's how you do it:
First, start editing your template.
Then search for the special tag which looks like this:

<$BlogItemBody$>

Usually this tag is contained by a <p> tag, a <div> tag, or both. One of these containing tags probably has a class name used for graphic design purposes. In the template I worked on, that class name was "post-body". I assume this is the case in most templates.
The class name we found is the class we need to change from left to right or right to left.
For this you need to add the following piece of code to the end of the template:


<script language="javascript">

window.onload = applyRTL;

// This fucntion applies right-to-left style to posts
// that contains hebrew:
function applyRTL()
{
 var arrDivs = document.getElementsByTagName("DIV");
 var i;
 var divPostBody;

 for (i = 0; i < arrDivs.length; i++)
 {
  divPostBody = arrDivs[i];
  
  if (divPostBody.className.toLowerCase() == 'post-body')
  {
   if (divPostBody.innerHTML.search(/[a-z]/) > -1)
   {
    divPostBody.style.direction = "ltr";
    divPostBody.style.textAlign = "left";
   }
   else
   {
    divPostBody.style.direction = "rtl";
    divPostBody.style.textAlign = "right";
   }
  }
 }
}

</script>

This code will execute once the page and all of the posts in it were loaded, and will make every post that contains hebrew letters right-to-left and every other post left-to-right.
In case the class name from above is different in your template, change 'post-body' in the line:

  if (divPostBody.className.toLowerCase() == 'post-body')

to the name of the class in your template.

Since what that code does is basically search your posts for specific letters, you can change it to search for specific phrases and change the appearance of your posts according to their content.

Using client-side scripts inside your blog can do a lot of other cool stuff - any ideas anyone?

New Google Service

2006-08-05T17:58:00.001+03:00

I've managed to put my hands on some top secret images of a very interesting new Google service... (enlarge for details)

I'll be the first one to sign up!

Hope you all enjoy it as much as I did :)
Yanir

רוג'ר, מאחוריך

2006-06-26T22:36:00.000+03:00

אז יצאנו מההופעה, עייפים אך מרוצים עד מאוד.
הייתה אחלה הופעה, עמדנו במיקום מצוין והסאונד היה מדהים - והשירים גדולים כפי שתמיד היו ותמיד יהיו.

הגענו לרכב ב 12:30, ופתחנו את הרדיו בפקקים.
כמובן שמיד חיפשנו תחנות שמדברות על ההופעה שזה עתה נגמרה, כי תמיד כיף לשמוע על עצמך ברדיו. רצה הגורל ונחתנו על תוכניתו של ניסים גרמה ברשת ב'.

ניסים מאוד התעניין בשמועות על השימוש של רוג'ר ווטרס בפלייבק במהלך ההופעה, בכדי לכסות על יכולות השירה שלו שידעו ימים יפים יותר.
שוחח ניסים עם מעין כתב מן השטח, ש"גם הוא זמר" לדבריו (כמובן שמעולם לא שמעתי את שמו). הזמר הלא ידוע אישר שאמנם לא שמו לב וזה היה עשוי היטב, אך בשיר אחד הוא הבחין בכך שייתכן וזהו פלייבק.

וכך ניסים גרמה:

"אני לא יודע אם הוא באמת השתמש בפלייבק, אבל אם כן הוא צריך להתבייש בעצמו. זה לא רציני".

וובכן, רוג'ר, תתבייש לך.
כנראה שיש לך עוד מה ללמוד כדי להגיע לסטנדרט הגבוה שדרוש כדי להצליח בארץ.

Why Google is the Next Big Thing

2006-04-24T01:37:00.000+03:00

Why is Google the next big thing?
Because Google has the three U's that will make it the number one software company in the world.

The first U stands for Understanding.

Google understands the future.

Billions of people today use Google software through their PC's or PDA's,
but Google understands this is only the very beginning. In the future, the number of devices that are connected to the internet will grow in such a way today's numbers will be negligible. It has already started with internet on cell phones, and it will continue with internet connections in your car, in your TV, in your radio, and even in your fridge. Think about it, you switch the channel on TV a lot more often then you search for something on the web. Can you imagine those little Google Ads appearing under the show details on cable TV? I sure can.
So if you think Google is already "the big thing", think again.

Google also understands that information is everything.

Google's mission is to organize the world's information.
Google understands that you can easily take out the word "information" and say the exact same thing: their mission is to organize the world.
What is the information Google talks about?
The answer to that question is somewhat similar to the answer to "what is the matrix" - information is all around you. You can see it when you look out the window, when you turn on your TV, when you pay your taxes.
Today Google organizes your web content, your e-mail, and even your calendar. In the future they can organize your taxes, your cable TV, and even your fridge.

Okay, understanding what the world is all about and what it will be like in the future is important, but that's an understanding a lot of us share, and by itself it's clearly not enough to become the next big thing.

The second U stands for Unification.

Google works hard to unify its services, a task it probably learned (and learned well) from its sworn enemy nowadays, Microsoft.
This unification means that everything you can do with Google services is connected to every other thing you can do with other Google services. It means that if I want to search my e-mail, it's as easy as searching the web with Google. It means that if I want to set a meeting with my friend all I have to do is e-mail him using my Gmail account and add a little note in my Google calendar. It means that if I want to chat with my friend online before sending the e-mail, I don't have to use a different software. It means that if I need to find some detail he mentioned during that chat I can search my mailbox the same way I search any other e-mail.

It eventually means that it is going to be easier for a user to use Google software instead of using lots of different services that don't fit together as nicely.

Unification is one of the major principles that got Microsoft to where it is today.
It is easier for the user to use Word, Excel, and Windows Media Player, simply because he is using Windows, and they go so well together - and it will probably take Google just as far.

The last U stands for Usability.

Google has a unique approach to usability.
Back in the 90's, Microsoft used to be the kings of usability.
Their software was simply the easiest to use, and that is the number one reason everybody uses Microsoft Windows today. When we migrated from Oracle database to Microsoft SQL Server, it was such a relief! It was amazing to see how much easier it was to work with Microsoft products. There are other consideration of course for working (or not working) with Microsoft products, such as reliability or efficiency
- but that's a different discussion.
The point is, Microsoft products were always so simple to work with, and for the average user, that's enough. And guess what - it turns out there are a lot more average users than linux geeks out there...

So why can't Microsoft keep up with Google?
Because usability is not what it used to be.
Usability today doesn't only mean that it's easy to use the product.
Usability for me is that I have 2.7 GB of storage in my Gmail account, instead of 2 MB in my previous hotmail account. It means that 99% of the junk mail I recieve is going automatically into my junk mail folder, instead of only about 50% in my previous hotmail account. It means that it's easier for me to type only the first few letters and not the full address of my reciepent. It means that it's easier for me to quickly type "Status meeting next wednesday 9:00" in Google calendar than it is to search for the right time in my outlook.

That is why today Google products are much more usable than Microsoft products (or any other company), and that is why I believe they will win the fight over the internet.

Google is doing what every other internet software company is doing (or at least trying to do).
Simply put, they are doing it better.

Resistance is Futile

2006-04-12T18:42:00.000+03:00

מעטים יודעים זאת, אך אי שם בתחילת הרבעון השני של שנת 2006 המציא בחור צעיר, ככל הנראה ממוצא איטלקי, את האנטי-בלוג.

האנטי-בלוג הוא אוסף של מידע חדש ומעניין.
הוא כתוב ללא הומור, אך רק במידה הנכונה.
הוא כתוב באופן מאוד פורמלי, ומאוד לא אישי.
הוא אינו מכיל קישורים לאנטי-בלוגים נוספים.
הוא אינו מכיל תגובות לאנטי-פוסטים של אנטי-בלוגרים אחרים.
באנטי-בלוג אין משחקי מילים.
אין בו הצהרות פוליטיות.
אין בו דבר המרמז על דעותיו של הכותב או תחומי העניין שלו,
וחשוב מכל, אין באנטי-בלוג דבר המוכיח את יכולת הכותב המדהימה להתבטא בכתב.
האנטי-בלוג אינו מהווה חלק מן "הקהילה".

לצערנו, ברגע עליית האנטי-בלוג לאוויר, חלה התנגשות בלתי נמנעת עם הבלוגוספירה הישראלית.
מאחר וכידוע בלוג ואנטי-בלוג נוהגים לפתח אלרגיות חמורות זה לזה, לא איחרה לבוא התפוצצות קוסמית שמחקה לחלוטין את האנטי-בלוג מן הקיום האנושי.

הצעיר, ככל הנראה ממוצא איטלקי, משך בכתפיו והמציא את האנטי-פסטי במקום.

בלוג זה לא יהיה שונה מבלוגים אחרים שקראתם.
הוא יהיה, ככל הנראה, אוסף של מידע ישן ומשעמם.
הוא יהיה כתוב בהומור, אך רק במידה הנכונה.
הוא יהיה כתוב באופן אישי ולא פורמלי.
כנראה שיכיל קישורים לבלוגים נוספים.
כנראה שיכיל אף תגובות לפוסטים של בלוגרים אחרים.
קרוב לוודאי שיהיו בו משחקי מילים.
הצהרות פוליטיות? אולי.
הוא כנראה ירמוז על דעותיו של הכותב או תחומי העניין שלו,
ואף יוכיח את יכולת הכותב המדהימה להתבטא בכתב.
ועם קצת מזל, הבלוג אפילו יהווה חלק מן "הקהילה".