Monthly Archives: September 2011

Good comments, Bad comments

/**
/* Vietnamese:
/* Đôi điều suy nghĩ về cách thức ghi chú (comment) trong mã nguồn.
/* Nếu bạn là một lập trình viên từng bực mình đến phát điên vì ai đó code “chuối”,
/* có lẽ bạn sẽ quan tâm đến những điều tôi viết dưới đây
**/

Not too long ago, I came across an “interesting” question on StackOverflow. It was “What is the best comment you have ever seen?“.

The answer list is very very long with thousands of comments. The highest-voted answer is a comment “placed far, far down a poorly-designed God Object“:

/**
* For the brave souls who get this far: You are the chosen ones,
* the valiant knights of programming who toil away, without rest,
* fixing our most awful code. To you, true saviors, kings of men,
* I say this: never gonna give you up, never gonna let you down,
* never gonna run around and desert you... /*a lot more here*/
*/

Well, it seems all of us developers need a little humor to spice up our steady (sometimes tedious) work. In a work environment with lots of tension, laughs are always loved.

But the thing that caught my eyes in that SO question is not humor. I mean dirty code, which smell through the comments.

// somedev1 - 6/7/02 Adding temporary tracking of Login screen
// somedev2 - 5/22/07 Temporary my ass

From that comment, you see how long a hotfix can live.

#define TRUE FALSE //Happy debugging suckers

If you quit your job, at least don’t treat the maintainers like that.

//Dear future me. Please forgive me.
//I can't even begin to express how sorry I am.

You may think it’s funny. Actually, to me it’s not. Please remember that 60% of developing effort is put on, not coding, but debugging.

Bad code along with poor comments is truly a nightmare to developers. Do you want days in & days out fix bugs caused by comments like this, please go on:

/** * Always returns true. */
public boolean isAvailable()
{
return false;
}

So the question is that: how good a comment should be?

Accoring to Robert C. Martin, comments don’t make up for bad codes. In stead, code should speak for itself, by good naming & structure. For a very simple example, the following code doesn’t have a comment, but it should be fine by itself:

      User currentUser = userService.getCurrentUser();
      if (currentUser != null) {
            if (urlOnlyAllowAnonymousAccess(requestUrl)) {
                log.info("An authenticated user try to access a non-logged-in link. Redirect to homepage");
                httpServletResponse.sendRedirect(contextPath + "/account/home.do");
                return;
            }

            if (urlNotAllowNonActivatedTVAccess(requestUrl)) {
                TVTracking tvTracking = currentUser.getAssociatedTV();

                if (tvTracking == null) {
                    log.info("A non-activated user is trying to access settings. Redirecting to activation page");
                    httpServletResponse.sendRedirect(contextPath + "/account/activate.do");
                    return;
                }
            }
        }

Upper case, lower case: SVN case-sensitive troubles

phong lan/** Vietnamese: Suy nghĩ về vấn đề phân biệt chữ hoa chữ thường khi làm việc với SVN **/

When it comes to source code control, it seems natural that SVN (Apache Subversion) is the most popular. Its opponent is not in good condition: Git is hard to learn and CVS is too old.

But tools can’t be always perfect, and SVN is no exception.

 

 

Problem:

You upload file “a_File.html” to server, then access it as “http://www.your_domain.com/A_File.html“. It returns a 404 – file not found. After some effort, you realize that your Linux server think “A_File.html” is different to “a_File.html”.

Fair enough. You are going to rename your file to “A_File.html”. And “bang”, Tortoise SVN shout out the red message: repository folder is locked, please execute clean up command.

You may even try some other tricks, like delete the folder and do “update” again – but things won’t change.

Reason:

Like mention above: the Linux server is case-sensitive, but Windows does not. Changing file name from “a.txt” to “A.TXT” make the conflict popout

Solutions:

1. If you want to change SVN file name on Windows, use the rename function of Tortoise SVN. Even in that case, changing from “a.txt” -> “A.TXT” often requires a “median” file name:(“a.txt” -> “b.txt” -> “A.TXT”).

2. If you don’t want to use that work-around, you can use “browse the repository” to rename that file (remoting) on the Linux server. Then delete your local file and do an update. If the errors persist, do a new checkout.

It’s kind of surprise to me that this kind of problems persist too long. Many know about it, many work-around were proposed, but no elegent way are made to solve the problem. Take a look around StackOverflow and I found dozens of related questions.

People seems to be busy with other big things.